
























                                     C L A C O M




                               Communications Library


                                         For


                             Clarion Database Developer






          Copyright (C) 1993 - 1994 by GAP Development Company.


          ALL RIGHTS  RESERVED. No part of this manual shall be reproduced,
          stored in  a retrieval  system,  or  transmitted  by  any  means,
          electronic, mechanical,  photocopying, recording,  or  otherwise,
          without written  permission from  GAP Development  Company. While
          every precaution  has been  taken  in  the  preparation  of  this
          manual, GAP  Development Company  assumes no  responsibility  for
          errors or omissions. Neither is any liability assumed for damages
          resulting from the use of the information contained herein.


          CLACOM is  the sole  and exclusive  property of  GAP  Development
          Company. It  is licensed  and not  sold  to  the  end  user  with
          restrictions placed upon its use.






          CLACOM is copyrighted by GAP Development Company.
          Clarion and Clarion Database Developer are trademarks of Clarion
          Software Corporation.
          DESQview is a trademark of Quarterdeck.
          DigiBoard is a trademark of DigiBoard Incorporated.






          Contents



          Description                                                     5

               Major Features                                             5


          Getting Started                                                 6



          Integrating with Clarion                                        7

               Overlays - Protected Mode                                  8
               Communications Interface                                   9
               File Transfers                                            11
               KeyCodes                                                  12


          Port Initialization                                            14



          Input & Output                                                 17



          Sample Application                                             21



          Global Variables                                               23



          Functions - Quick Reference                                    24



          Functions - Detailed Reference                                 25



          Appendix A                                                     69





                                       Page 3






          Appendix B                                                     72



          Index                                                          73














































                                       Page 4



          GAP Communications                                         CLACOM




          Description


          CLACOM is  a professional  communications library for programmers
          using the  Clarion Database  Developer. It  allows you  to easily
          integrate asynchronous communications into your Clarion programs.

          CLACOM includes  robust Communications  routines which  are fully
          interrupt driven. Written in highly optimized assembler, they are
          capable of  operating at  any speed which the UART on an IBM type
          of computer  is capable  of producing.  The FIFO  buffers in  the
          16550 UART  are fully  supported. Hardware  flow control (CTS/RTS
          checking) is automatic.

          ANSI Terminal  Emulation is  fully integrated into CLACOM, as are
          the most popular file transfer protocols.


          Major Features

              Supports the FIFO buffers of the 16550 UART chip.
              Speeds up to 115,200 baud.
              Supports COM  1 through  COM 4  as  well  as  Intelligent
               DigiBoards using  a Direct  Programming  Interface  or  a
               DigiBoard Device Driver.
              Up to 4 ports can be opened simultaneously (16 ports when
               using a DigiBoard).
              Supports CTS/RTS, automatically.
              Fully self  contained, built  in ANSI driver for IBM ANSI
               Terminal Emulation.
              File transfer  protocols include - ASCII, Xmodem, Xmodem-
               CRC,  1K  Xmodem,  1K  Xmodem-G,  Ymodem,  Ymodem-G,  and
               Zmodem.
              Works with  programs compiled as Static, Overlay, Overlay
               with DLL, Protected, and Protected with DLL.
              Extremely easy interfacing with Clarion programs.













                                       Page 5



          GAP Communications                                         CLACOM


          Getting Started


          First a  note about this documentation. This Text Based manual is
          identical in  content to  the Printed Manual except that it lacks
          formatting and  graphics. Some screens can not be reproduced in a
          document such  as this.  Font  sizes  can  not  be  changed  when
          necessary since  there is  no way of knowing what kind of printer
          this document  will  be  printed  with.  The  Printed  Manual  is
          designed in  such a way that it is easy to read and it is easy to
          find the  information you may be looking for. We are unable to do
          the same  with this  text  based  manual.  If  the  documentation
          references a  screen, you will need to run the Example program to
          see the  screen, since we are unable to reproduce it in this Text
          Based manual.



          The following files are part of the CLACOM distribution set:

              CLACOM.TXT    - Text Based documentation. Not part of
                              Registered version since its not needed.
              DXVCLOM.LIB   - Library routines for Statically linked
                              Clarion APP.
              DOVCLCOM.LIB  - Library routines for Overlayed Clarion APP.
              DDVCLCOM.LIB  - Library routines for Overlayed Clarion APP
                              using Run Time Librares.
              DESCLCOM.LIB  - Library routines for Protected mode Clarion
                              APP using Run Time Libraries.             (1)
              DEVCLCOM.LIB  - Library routines for Statically linked
                              Protected mode Clarion APP.               (1)
              CLACOM.OBJ    - Stub for including Module Definitions.
              CLACOM.INC    - Module Structure Include file.
              GTERM.ZIP     - Terminal Emulation example with Clarion
                              source.
              RESETDIG.ZIP  - Program used to reset a DigiBoard COM/Xi.


          The .OBJ,  .LIB and  .INC files  should be  placed  in  the  same
          directory where  the program you intend to use them with resides.
          GTERM.ZIP contains  a Terminal  Emulation Clarion Application. It
          should be  placed in its own directory along with the above .OBJ,
          .LIB and .INC files.



          (1) Protected  Mode Libraries  are not  included  with  Shareware
              version of CLACom.



                                       Page 6



          GAP Communications                                         CLACOM






          Integrating with Clarion


          To tell  your Clarion  Application that  you are using the CLACOM
          library, follow these steps:

          Load or Create your application.

          From the  View Menu,  select Module  View. Select Insert from the
          Edit Menu.  The Module  Properties screen  will appear.  For  the
          Module Name,  type CLACOM.OBJ.  Select the External Object Module
          radio  button.  For  the  Module  Structure  Include  File,  type
          CLACOM.INC. Select OK.

          CLACOM.OBJ is  a dummy  module. It  contains no code or data. Its
          sole purpose is to include the CLACOM procedure definitions.

          You must  now edit  the Project  File and include the five CLACOM
          libraries. The  fivee libraries  are identical with the exception
          that they  were compiled  using one  of the  five Clarion  memory
          models:  Static,  Overlayed,  Overlayed/Runtime,  Protected,  and
          Protected/Runtime.

          Select the  Project Menu.  Select Change Project File. Select the
          Module button  and then  the Insert  button. For the Module Name,
          type:

                                  %CLAPFX%CLCOM.LIB

          Select the  External OBJ/LIB  Radio  button.  Finally,  save  the
          Project File changes.

          Your Clarion application is now fully aware of the CLACOM library
          routines and  you will  be free  to use  any of the five standard
          Memory Models  without having to worry about which CLACOM library
          to use.











                                       Page 7



          GAP Communications                                         CLACOM


          Overlays - Protected Mode

          You must  perform one  final step  before generating  your CLACOM
          application.

          The Standard  Communications interface  takes over  the interrupt
          vector for  the selected  COM Port. This means that the interrupt
          service routine  can not be swapped out. It must remain in memory
          at all  times. The  same is  true if  you enable  the  Ctrl-Break
          intercept routine (which you should).

          In order  to keep  the  Communications  routines  in  memory  and
          prevent them  from being  swapped out,  you must make a change to
          one of  Clarion's files. In the Clarion directory there is a file
          called ROVERLAY.EXP.  Edit this  file and add the following lines
          to the end of the SEGMENTS section:

               GCOM_DATA      PRELOAD   FIXED
               GCOM_TEXT      PRELOAD   FIXED

          A portion of the ROVERLAY.EXP file would appear as follows:



                       CLAICEP_TEXT     PRELOAD
                       CLAFIXED_DATA    PRELOAD
                       GCOM_DATA        PRELOAD   FIXED
                       GCOM_TEXT        PRELOAD   FIXED


          Please do not take the above change lightly or forget to make it.
          Failure to  add the  above lines will cause your program to crash
          as soon as the communications routines are swapped out of memory.
          This is  especially important  for Protected Mode programs as you
          want the Communications routines to remain FIXED in memory.

          You may  also copy  this file  to your  application's  directory,
          giving it  the name  of your application with the .EXP extension:
          APPNAME.EXP.

          Adding the  above lines to your Export file will not, in any way,
          interfere with applications that do not use CLACOM.









                                       Page 8



          GAP Communications                                         CLACOM


          Communications Interface

          CLACOM supports three serial port interfaces:



                    STANDARD    DIGIBOARD   INT14/EBIOS

          The standard  interface is  used when  working with  the standard
          COM1 thru  COM4 serial  ports on  the Host computer. This will be
          the interface  most often  used.  If  an  end  user  is  using  a
          DigiBoard then  either the DigiBoard or Int14/EBIOS interface may
          be selected.  Most  DigiBoard  users  will  use  the  Int14/EBIOS
          interface. All  input/output to  the DigiBoard  is performed  via
          Interrupt 14  calls and  a Device  Driver (supplied by DigiBoard)
          handles the  interface between  the program  and the  board.  The
          DigiBoard interface  uses Direct Programming. CLACOM talks to the
          board directly  without the need for a Device Driver. In order to
          use this interface, a program called RESETDIG.EXE must be used in
          the AUTOEXEC.BAT  file to  reset  the  DigiBoard  once  when  the
          computer is first booted. This program is supplied as part of the
          CLACOM package and may be freely distributed to your end users.

          In order to determine which interface your end users require, you
          should provide a Hardware screen similar to the following:




                  SCREEN NOT AVAILABLE IN TEXT BASED DOCUMENTATION
                                 SEE EXAMPLE PROGAM




          If the Standard Interface is selected, the Ports Button should be
          enabled, the  DigiBoard Button  disabled, and if the Ports Button
          is  selected,  a  screen  similar  to  the  following  should  be
          displayed:




                  SCREEN NOT AVAILABLE IN TEXT BASED DOCUMENTATION
                                 SEE EXAMPLE PROGAM






                                       Page 9



          GAP Communications                                         CLACOM


          If the  DigiBoard or Int14/EBIOS Interface is selected, the Ports
          Button should  be disabled,  the DigiBoard Button enabled, and if
          the DigiBoard  Button  is  selected,  a  screen  similar  to  the
          following should be displayed:




                  SCREEN NOT AVAILABLE IN TEXT BASED DOCUMENTATION
                                 SEE EXAMPLE PROGAM




          On the Hardware Screen, if the DigiBoard or Int14/EBIOS Interface
          is selected,  then the  Port Radio Buttons should be disabled. On
          the Port  Assignments Screen,  the Base  and IRQ fields for COM 1
          and COM 2 should be marked as "Skip". The reason for this is that
          it makes  no difference what a user types into these fields since
          the standard  Base Address  and IRQ  for these  two ports will be
          used.

          On the  DigiBoard Parameters  Screen, the  fields that need to be
          disabled  depend   upon  the   Interface.  If  the  Interface  is
          DigiBoard, then the Memory Window and I/O Port Buttons are valid,
          as is  the Channel  Number field.  Channel Numbers for the Direct
          Interface generally  range from  1 to 16. The sample screens show
          the valid Window and I/O Port address for a DigiBoard.

          If, however,  the Interface is Int14/EBIOS, the Memory Window and
          I/O Port  Buttons should  be disabled.  Only the  Channel  Number
          field should  be selectable.  The Int14/EBIOS  Interface uses the
          DigiBoard supplied  Device Driver  and it  already knows what the
          addresses for  the board  are, so  these Radio  Buttons  are  not
          needed for  this Interface.  Channel numbers  for this  Interface
          generally range  from 4  to 19  (0 -  3 are  reserved for  COM1 -
          COM4).

          Don't try  to do range checking on the DigiBoard Channel Numbers.
          These boards  are produced  in several  varieties from 2 ports, 8
          ports, up to 16 ports. An end user that is using a DigiBoard will
          likely know what Channel Number is being configured.

          When using  the DigiBoard  Interface an  end user that is using a
          DigiBoard will  also know what Memory Window and I/O Port address
          the board  was configured  for when  the board was installed. The
          valid addresses  are contained  in the  DigiBoard manuals and are
          shown on the sample screens.



                                       Page 10



          GAP Communications                                         CLACOM


          Keep in mind that in order to use the DigiBoard Direct Interface,
          your end  users must  run the  supplied RESETDIG.EXE  program  in
          their AUTOEXEC.BAT  files. This  program makes sure the DigiBoard
          is reset and able to accept commands when the computer is powered
          on. It  resets all  of the Channels on the board, which is why it
          is run only once.


          File Transfers

          CLACOM supports  all of the popular File Transfer Protocols. Each
          of the  protocols are  given a  number  (with  the  exception  of
          Zmodem). Before  initiating an  Upload or a Download, you need to
          prompt the user for a Protocol. Your end users won't be the least
          bit impressed  about having  to type in a number so your Protocol
          Browse Box  should display Protocol Names. In the background, you
          will translate  the Names  into numbers  to send  to the protocol
          drivers. The  sample Terminal  Program shows an excellent example
          of how  to prompt  for a Protocol and translate the string into a
          number to  send  to  the  protocol  drivers.  The  Protocols  are
          numbered as follows:



                    0 - ASCII         3 - 1K Xmodem-G
                    1 - Xmodem        4 - Ymodem
                    2 - 1K Xmodem     5 - Ymodem-G


          Note that  as far  as CLACOM is concerned, there is no difference
          between Checksum  Xmodem and  CRC Xmodem. CLACOM always starts in
          "CRC Mode" but will adjust itself as necessary.

          Also note  that both  of the Ymodem protocols (as well as Zmodem)
          are Batch Protocols and when Downloading, you need not prompt for
          a File  Name since  the name will be supplied by the sender. When
          Uploading you  can either provide a single File Name to upload or
          a Wild Card specification.













                                       Page 11



          GAP Communications                                         CLACOM


          KeyCodes

          CLACOM includes  a function  called GetKeyc.  If your application
          needs to  send  keycodes  that  were  generated  from  the  local
          keyboard out  the Communications  Port to  a remote  computer you
          need to  use  this  function  to  gather  input  from  the  local
          keyboard. Clarion's  keyboard routines  can not  be used  because
          Clarion changes  the value  of certain key presses (including the
          standard ASCII codes, 0 - 255).

          For instance,  Clarion re-maps  the  following  keys  from  their
          standard ASCII value to a value meaningful only to Clarion:

                      Key         Clarion   Actual

                      Escape         256      27
                      Enter          257      13
                      Backspace      258       8


          If you  use the Clarion keyboard functions and a user presses the
          backspace key,  Clarion returns  a code  of 258. If you send this
          keycode to the remote computer, what you will actually be sending
          is the  code 2  (Clarion's keyboard  functions return  a LONG and
          Communications Ports  can only  accept a BYTE, therefore the high
          bytes of  the return  value are truncated and only the lower byte
          is sent).  The remote  computer will either display the character
          (a happy  face) or  act upon  it (to the remote computer, it is a
          Ctrl-B). The  remote computer  will not know that you were trying
          to backspace over a previously typed character!

          Any character  typed at the keyboard is a valid character to send
          out the  Communications Port if that character has a value of 255
          or less. It shouldn't be re-mapped or translated in any manner.

          GetKeyc  returns   keyboard  characters  "as  is".  It  makes  no
          translations on  regular ASCII  characters (0  - 255).  Any  code
          above 255 (an Extended Keyboard code) returns the actual keyboard
          scan code for that key with the value 256 added. By adding 256 to
          the value  you can  easily determine  if the  key is an exteneded
          key. A  Backspace is  code 8.  An Enter  is code 13. An Escape is
          code 27.

          Because  Clarion  includes  its  Keyboard  Equate  file  in  your
          application, there  are no  supplied mnemonics  for the  keycodes
          that GetKeyc  returns. Appendix  A shows the actual key typed and
          the value  returned by GetKeyc. You can not use BSKey to see if a
          key press  is the  Back Space  key because  of the  keyboard  re-



                                       Page 12



          GAP Communications                                         CLACOM


          mapping equates that Clarion includes in your program. If you do,
          you will  be testing  against the  code 258  when you  need to be
          testing against the code 8.

          For instance, this will not work:

             keychr = GetKeyc()                   ! Get Key Press

             if keychr = BSKey                    ! Backspace hit
               ComPutc(keychr)                    ! Actually sends a Ctrl-B
             end

          This will work:

             keychr = GetKeyc()                   ! Get Key Press

             if keychr = 8                        ! Backspace hit
               ComPutc(keychr)                    ! Sends an 8 (backspace)
             end
































                                       Page 13



          GAP Communications                                         CLACOM


          Port Initialization


          The  first  thing  a  communications  program  normally  does  is
          initialize the  communications port and reset the modem. You will
          notice that the sample program, GTERM, takes a different approach
          to the  usual "terminal"  interface and it doesn't initialize the
          port until it is ready to use it.

          How you  initialize the  communications port  depends upon  which
          Interface the  user has  selected. The  DigiBoard and Int14/EBIOS
          Interfaces set  up the  port in  a single  step process.  This is
          because some of the low level routines either in the Int14 Device
          Driver or  the on-board BIOS require that all parameters be known
          when initializing a port on the board.

          Setting up  the Standard  Interface is  a two  step process.  The
          first step  is to  set up the Interrupt Handler, program the UART
          to generate  interrupts, turn the FIFO buffers on (if the UART is
          a 16550)  and program  the Interrupt  Controller chip  so that it
          will recognize the UART interrupts. The second step is to set the
          Line Control register in the UART. This is more commonly known as
          setting the Baud Rate, Party, Data, and Stop bits

          Port Numbers  for the Standard and DigiBoard Direct Interface are
          0 based.  Your users will not be accustomed to entering 0 for COM
          1 or  1 for  COM 2, therefore your applications should use 1 when
          referring to  COM 1,  2 when referring to COM 2, 3 when referring
          to COM  3, etc.,  and you should make the translations to 0 based
          ports before  calling any  of the  Communications routines.  Note
          that the  INT14/EBIOS Interface uses port numbers that begin with
          1.

          The following  is an  example on  setting up  the  communications
          port. The  first step  is to  initialize the ANSI driver. This is
          important so that the screen output functions know how large your
          Terminal Screen  is and  the default  color you  want to use. You
          must pass  the COM  port number  that the  ANSI  driver  will  be
          associated with.  The ANSI  Cursor Position Report (CPR) sequence
          is issued  whenever the  driver receives  a Device  Status Report
          (DSR) command.  The CPR  sequence is sent out the COM port. Since
          there is  only one  screen and  one ANSI  driver, the driver must
          know which  port to use. The DSR/CPR sequences are generally only
          used by  BBS  programs  to  determine  if  the  caller  has  ANSI
          capability. The  second step  is to determine which Interface the
          user is using and setup the port accordingly:





                                       Page 14



          GAP Communications                                         CLACOM


             InitAnsi(comport,MaxRows,MaxCols,14) ! Initialize Ansi Driver

             BaudRate = DEFORMAT(GCN:BaudRate)    ! string to number

             data = deformat(GCN:Data)            ! get Data
             stop = deformat(GCN:Stop)            ! Stop

             if GCN:Parity = 'Odd'                ! and Parity
               parity = 1
             elsif GCN:Parity = 'Even'
               parity = 2
             else
               parity = 0
             end

             gotdigi = 0                          ! assume no DigiBoard

             if clip(GCN:Interface) = 'DigiBoard' ! using DigiBoard
               comport = GCN:DigiChnl - 1         ! 0 base the Port #
               gotdigi = 1                        ! set DigiBoard flag
               anystring = GCN:DigiSeg            ! get Memory Window
               digiseg = StrHex(anystring)        ! as a Hex Number
               anystring = GCN:DigiPort           ! get I/O Port
               digiport = StrHex(anystring)       ! as a Hex Number

               retcode = DsetUp(DigiSeg,DigiPort,comport,BaudRate
                                parity,data,stop)

               if retcode > 0
                 ! display error message and quit
               end

             elsif clip(GCN:Interface) = 'Int14/EBIOS' ! using Int14/EBIOS
               comport = GCN:DigiChnl                  ! Port Number
               gotdigi = 1                             ! set DigiBoard flag

               retcode = Int14Set(comport,BaudRate,parity,data,stop)

               if retcode > 0
                 ! display error message and quit
               end










                                       Page 15



          GAP Communications                                         CLACOM


             else                                 ! Regular Interface

               ! get Port, IRQ, and BASE Address

               IRQ = 0
               base = 0

               if GCN:Port = 'COM1'
                 comport = 0
               elsif GCN:Port = 'COM2'
                 comport = 1
               elsif GCN:Port = 'COM3'
                 comport = 2
                 IRQ = GCN:IRQ3
                 anystring = GCN:BASE3
                 base = StrHex(anystring)
               elsif GCN:Port = 'COM4'
                 comport = 3
                 IRQ = GCN:IRQ4
                 anystring = GCN:BASE4
                 base = StrHex(anystring)
               end
               
               ! initialize COM Port and Interrupt Vector

               retcode = SetPort(IRQ,base,comport)

               if retcode > 0
                 ! display error message and quit
               else
                 ! Set Baud, Parity, Data, and Stop

                 retcode = InitPort(comport,BaudRate,parity,data,stop)

                 if retcode > 0
                   ResetPort()                    ! Interrupts Off
                   ! display error message and quit
                 end
               end
             end


          As you can see when using the Standard Interface and there are no
          errors setting up the Port, we then call InitPort to set the Baud
          Rate, Data, etc.






                                       Page 16



          GAP Communications                                         CLACOM


          Input & Output


          To gather input from the local keyboard, GetKeyc is used. GetKeyc
          returns a  SHORT. If  the return  value is  less than 0 then that
          means no  key was  pressed (GetKeyc actually returns a -1 in this
          case). If the return value is greater than 255 then that means an
          extended key was pressed (function key, cursor pad key, etc). You
          normally do  not send  these extended keys out the communications
          port unless  the remote  end can accept and handle extended keys.
          If the  remote end  can handle extended keys, the usual procedure
          for sending  these keys is to first send a 0, then send the lower
          8 bits  of the  return value. If the return value is less than or
          equal to 255, then you assign the return value to a BYTE and call
          ComPutc to send the keyboard code.

          The following  example shows how to use GetKeyc and interpret the
          return value.  Note that we do not use the Clarion KeyCode Equate
          labels since they are mapped to different codes:

             comport SHORT
             retchr  SHORT
             keychr  BYTE

             retchr = GetKeyc()           ! get a keyboard character

             if retchr NOT= -1            ! if something there
               if retchr > 255            ! Extended Key
                 case retchr              ! which one
                   of 278                 ! Alt-U, Upload a File
                   of 288                 ! Alt-D, Download a File
                   of 369                 ! Alt-F10, activate Menu
                 end
               else                       ! regular keyboard key
                 keychr = retchr          ! Translate to BYTE value
                 ComPutc(comport,keychr)  ! and send it out
               end
             end













                                       Page 17



          GAP Communications                                         CLACOM


          The following  example is  similar to the above but in this case,
          the remote end can handle extended keyboard codes:

             comport SHORT
             retchr  SHORT
             keychr  BYTE

             retchr = GetKeyc()           ! get a keyboard character

             if retchr NOT= -1            ! if something there
               if retchr > 255            ! Extended Key
                 case retchr              ! which one
                   of 278                 ! Alt-U, Upload a File
                   of 288                 ! Alt-D, Download a File
                   of 369                 ! Alt-F10, activate Menu
                   else                   ! not something we care about
                     keychr = retchr      ! Translate to BYTE value
                     ComPutc(comport,0)   ! flag that this is extended key
                     ComPutc(comport,keychr)      ! send scan code
                 end
               else                       ! regular keyboard key
                 keychr = retchr          ! Translate to BYTE value
                 ComPutc(comport,keychr)  ! and send it out
               end
             end

          Whether or  not local  keyboard characters  are sent to the local
          screen depends  upon if you originated the connection or answered
          the connection.  Generally the  originating side does not display
          keyboard characters.  It simply  sends  the  characters  out  the
          communications  port   and  the   answering  side   displays  the
          characters on  its screen and sends the characters back, at which
          time you retrieve them from your receive buffer and display them.
          This is sometimes refered to as Full Duplex.

          Some answering  systems do not echo characters back to the sender
          (refered to  as Half  Duplex). In  this case,  you will  need  to
          display the  keyboard character  in addition to sending it to the
          communications port.

          If you are writing BBS software, you always display locally typed
          characters on the screen, and you always echo characters received
          from the  communications port  back out  the  port.  If  you  are
          writing Terminal  Emulation software,  whether or  not to display
          locally typed  characters on the screen is generally a Phone Book
          option for each entry in the phone book. Characters received from
          the communications port are never sent back out the port.




                                       Page 18



          GAP Communications                                         CLACOM


          The following  is an  example of  keyboard input  routines  where
          "Half Duplex" operation is required:

             comport SHORT
             retchr  SHORT
             keychr  BYTE
             halfdup BYTE

             halfdup = 1                  ! flag to use half duplex

             retchr = GetKeyc()           ! get a keyboard character

             if retchr NOT= -1            ! if something there
               if retchr < 256            ! regular character
                 keychr = retchr          ! Translate to BYTE value
                 ComPutc(comport,keychr)  ! and send it out

                 if halfdup               ! if half duplex
                   Gputc(keychr)          ! display on local screen
                 end
               end
             end


          A good  example of  Half Duplex  versus Full  Duplex is  when you
          enter into  Terminal Emulation  mode when  not connected  with  a
          remote  computer.   If  the  modem  is  configured  not  to  echo
          characters back,  then anything you type will not be displayed on
          the screen.  This is  because there  is no On Line service on the
          remote end to send the characters back. If you subsequently place
          an item  on the  Terminal Menu to toggle duplex from full to half
          and toggle  it to  half, then  what you type will be displayed on
          the  screen   (providing  you  write  the  code  to  handle  this
          situation, as in the above example).

          GPutc and GPuts are the local output routines. The first displays
          single characters  while the second displays entire strings. Both
          routines are  tied into the internal ANSI driver which means they
          can contain  ANSI display  sequences to  move the  cursor, change
          colors, clear the screen, etc.

          ComGetc is  the communications  port input  routine. It retrieves
          single byte values from the port. In order to distinguish between
          a no  character available  condition (empty receive buffer) and a
          legitimate character,  it returns  a negative value (-1) if there
          are no  characters waiting  to be  read. The return value must be
          assigned to a BYTE before it can be displayed by Gputc.




                                       Page 19



          GAP Communications                                         CLACOM


          An example of ComGetc and Gputc together:

             comport SHORT
             retchr  SHORT
             keychr  BYTE

             retchr = ComGetc(comport)    ! get a remote character

             if retchr NOT= -1            ! if something there
               keychr = retchr            ! Translate to BYTE value
               Gputc(keychr)              ! and display it
             end


          ComPutc and  ComPuts are  the communications output routines. The
          first sends  single characters  while  the  second  sends  entire
          strings.

          A word  about the  built in  ANSI driver  and Clarion.  The  ANSI
          driver writes  directly to  the video display memory (taking care
          to honor  DESQView's shadow  buffer if operating under DESQView).
          Because Clarion keeps a backup copy of the video display, Clarion
          will overwrite  anything placed on the screen by Gputc and Gputs.
          This occurs  because when  Clarion opens  a screen  or a menu, it
          first updates the physical screen with the contents of its backup
          buffer, then opens the screen. The only time this is a problem is
          when you  are in  Terminal  Mode  and  using  the  CLACOM  output
          routines.

          To circumvent  this problem  there is  a procedure called GetScrn
          which will  update Clarion's  backup buffer  with the contents of
          the physical  screen. This  procedure should  be called  prior to
          invoking a Clarion function that writes to the screen.


















                                       Page 20



          GAP Communications                                         CLACOM


          Sample Application


          Included with  CLACOM is  a  sample  Terminal  Emulation  program
          (called GTERM)  which shows how to use most of the communications
          routines.  You  may  use  this  application  as  a  template  for
          designing your own communications program.

          The First  Procedure is defined as InitProgram. InitProgram first
          arms a  ShutDown Procedure  called ResetCbreak.  In then  makes a
          call to  SetCbreak to  set up the Ctrl-Break handler (a necessary
          requirement for  any communications  program. ResetCbreak will be
          called automatically  when the  program ends.  It makes a call to
          RestCbreak to restore the Ctrl-Break handler.

          InitProgram then  checks to  see if  the Main  Configuration File
          exists. If  this is  the first  time the  program is run, it will
          create the configuration file with default values for each of the
          fields. It  then checks  to see  if the  Protocol File exists. If
          not, it creates the file with the 7 internal protocols. This data
          could be  set up  in a  Memory Queue,  but placing  it in  a file
          allows you  to create  an entry screen so that your users can add
          external  protocols.   You  will  see  from  examining  the  File
          Properties that  the fields  to allow  for external protocols are
          already in  the file.  If you  do create a Browse/Form for adding
          external protocols,  you need  to make sure that the user can not
          delete or change any of the internal protocols.

          InitProgram then  calls MainMenu. On MainMenu the user may select
          the Files Menu, which contains Quit, to exit the program.

          The Dial Menu brings up a Lookup screen where the user may select
          a Phone  Number to  call. The  Dialing Directory is tied into the
          EditPhone Form  so that a user may add or change an entry without
          having to go to the Setup Menu.

          When a  phone  number  has  been  selected,  the  Dial  Procedure
          initializes the  Communications Port  and calls  the number. Upon
          successful connection  with the remote computer it will place the
          user  in   Terminal  Mode.   Dial  gives  excellent  examples  on
          interfacing with a communications port and a modem.

          The Terminal  Menu puts  the user  directly into  Terminal  Mode.
          Because Terminal  Mode can be entered either directly or from the
          Dial Menu,  the procedure checks to see if it was called by Dial.
          If so, it won't attempt to initialize the Communications Port. If
          entered from  the Menu,  Terminal initializes the port in exactly
          the same  manner as  Dial,  with  one  exception.  For  the  Port



                                       Page 21



          GAP Communications                                         CLACOM


          parameters, instead  of  using  the  parameters  from  a  dialing
          directory entry, it uses the global default parameters.

          Terminal Mode is really the heart of the application. Whatever is
          received from the Communications Port is displayed on the screen.
          Incoming characters  are sent  to the ANSI Driver. If you wish to
          emulate a  TTY device,  instead of  sending the characters to the
          ANSI Driver,  you can  use Clarion's TYPE function (the character
          will first  have to  be converted  to a  string). Keyboard  codes
          (those entered  from the  local keyboard)  are checked  to see if
          they are  extended keys.  Any  keyboard  code  above  255  is  an
          extended key. If the key code is a regular keyboard character, it
          is sent  out the  Communications Port.  If the  key  code  is  an
          extended key  it is  checked to  see if it is the menu activation
          key (Alt-F10)  or one  of the  "hot keys".  If so,  the  routines
          associated with  those keys are invoked. If the key code is not a
          regular  ASCII   character  or  an  extended  key  that  Terminal
          recognizes it is simply discarded.

          Please see  the section Keycodes for more information on Extended
          Keyboard Codes  and why you need to use CLACOM's GetKeyc function
          to retrieve characters from the keyboard.

          Terminal includes  a Menu  that is activated by pressing the Alt-
          F10 key.  It allows  the user  to exit  Terminal Mode, Upload and
          Download Files,  Clear the  Screen, Change  Modem Parameters  and
          Hang Up  the modem  (drop carrier). You will notice that any menu
          function that  depends upon  there  being  a  remote  carrier  is
          disabled if there is no connection with a remote computer.

          Because Clarion  writes to the screen twice (once to video memory
          and once  to its  own backup  buffer) Clarion  doesn't know  that
          you've been using the ANSI driver to display characters. When you
          use Gputc  and Gputs  to send  incoming characters  to the CLACOM
          ANSI driver,  Clarion has no idea that you've been writing to the
          screen. While  in Terminal  Mode, before  you  call  any  Clarion
          Function that displays something on the screen (with the possible
          exception of  the TYPE  function) you  need to  update the backup
          buffer that  Clarion writes  to. This is accomplished with a call
          to GetScrn. GetScrn reads the contents of the physical screen and
          updates Clarion's  backup buffer  with the  information. Terminal
          shows how and when to call GetScrn. If you don't make the call to
          GetScrn then  Clarion will  erase whatever  is on  your  Terminal
          Screen before  it displays  the screen  you open. To get a better
          understanding for  this, comment  out all of the calls to GetScrn
          in the  Terminal Procedure. Then make and run the program. Make a
          connection to a remote computer. While in Terminal Mode, activate




                                       Page 22



          GAP Communications                                         CLACOM


          the  Menu  (Alt-F10).  Watch  what  is  on  the  screen  suddenly
          disappear!

          The Setup  Menu allows a user to set default Modem Parameters and
          enter Phone  Book entries.  The Modem  Parameters are used as the
          defaults for  each Phone  Book entry  and when  entering Terminal
          Mode from the Terminal Menu.

          GTERM gives excellent examples on how to use the CLACOM functions
          and procedures.  It can  be used  as a template to write powerful
          Terminal  Emulation   programs   that   include   more   terminal
          emulations, external  protocols,  script  files  (for  automating
          logons), keyboard  macros, Compuserve  or BBS  Message  handling,
          Screen Capturing, and lots more.

          GTERM can  be condensed so that your Mailing List Application can
          automatically dial a number contained in the data base. It can be
          expanded to become a popular Term program, even a BBS program!



          Global Variables


          The following  variables are  declared global  and may be used by
          your application  to alter  the behavior  of  the  Communications
          routines:

               noascmes   When set  to 1, disables all messages and windows
                          associated with  ASCII file  transfers.  This  is
                          useful   when    you   are    using   the   ASCII
                          upload/download routines for something other than
                          transferring files.
               nocts      When set  to 1,  disables the Clear To Send (CTS)
                          checking that  is performed by the Communications
                          Output routines. Should never be set unless there
                          is a specific reason for doing so.
               asciidel   The number  of clock  tics to delay after sending
                          each line  in a  file when  using the  ASCII file
                          transfer. 18 tics equals 1 second.











                                       Page 23



          GAP Communications                                         CLACOM


          Functions - Quick Reference


            CkeyPress    - Checks for a remote or local key press.
            ClrBuf       - Clear the communications receive buffer.
            ComGetc      - Gets a character from com port.
            ComGetd      - Gets a character from com port with time-out.
            ComPutb      - Sends a buffer of data to com port.
            ComPutc      - Sends a character to com port.
            ComPuts      - Sends a string to com port.
            CursorOff    - Turns local cursor off.
            CursorOn     - Turns local cursor on.
            DclrTx       - Clear DigiBoard Transmit buffer.
            DgtTxfree    - Get Free space in DigiBoard Transmit buffer.
            Dmodem       - Change DigiBoard Port parameters.
            DownLoad     - Download using Xmodem and Ymodem.
            Drestore     - Reset DigiBoard Port.
            DsetUp       - Initialize DigiBoard Port (Direct Interface).
            Dtr          - Toggles the DTR line on or off.
            GetKeyc      - Gets keyboard character and scan code.
            GetScrn      - Update Clarion's screen buffer.
            GetZmodem    - Download using Zmodem.
            Gputc        - Sends a character to local screen.
            Gputs        - Sends a string to local screen.
            InitAnsi     - Initializes ANSI driver.
            InitPort     - Sets up Communications Port (Std Interface).
            Int14Set     - Initialize DigiBoard Port (Int14/EBIOS Intface).
            Iscd         - Checks if there is a Carrier.
            ModemPuts    - Send a string to the modem.
            ModemStat    - Get Modem Status.
            PosCursor    - Update ANSI Driver Cursor Position.
            ResetPort    - Restores Communications Port (Std Interface).
            RestCbreak   - Restores Ctrl-Break vector.
            Rts          - Toggles RTS line on or off.
            Rxempty      - Checks if any characters in receive buffer.
            SendBreak    - Send a break signal to the modem.
            SendZmodem   - Send files using Zmodem.
            SetPort      - Initializes Communications port.
            SetCbreak    - Initializes Ctrl-Break vector.
            StrHex       - Translate Hex String to number.
            StrWord      - Find substring in string.
            Timer        - Time Delay.
            UpLoad       - Send files using Xmodem and Ymodem.








                                       Page 24



          GAP Communications                                         CLACOM


          Functions - Detailed Reference


          Functions return a value, procedures do not return anything.

          Procedures cannot  be used in assignment statements. They perform
          a service  and do not report back as to the successful completion
          of that service.

          Functions also  perform a  service but they do report back on how
          well that service was performed.

          The return  value from  a function must be assigned to a variable
          of like  type or  used in  a comparison statement (this is due to
          Clarion's strong type checking which will not allow you to call a
          function without checking its return value).

          The function  descriptions will note whether or not a function is
          actually a  Procedure (does  not return  a value)  or a  Function
          (does return a value).

          The Examples will use a string called "cstr" to let you know that
          the function  requires a string in the C, NULL terminated, format
          (CSTRING in  Clarion). Passing Clarion Strings to these functions
          will not  work. You  will need  to assign the Clarion STRING to a
          CSTRING and then pass the variable in the function call.

























                                       Page 25



          GAP Communications                                         CLACOM


          CkeyPress
          -----------------------------------------------------------------

          Purpose       Checks for a remote or local key press.

                        CkeyPress(port)

                        SHORT port                COM Port Number

          Type          Function - Returns SHORT

          Description   This function will check the local keyboard as well
                        as the  communications receive  buffer to  see if a
                        key is waiting to be read. It is most often used in
                        loops that  need to  wait for  a key  press, either
                        from remote or local.

          Return Value  0 = no key is waiting, 1 = a key is waiting.

          Example       c = CkeyPress(0)          ! key pressed?

             loop while CkeyPress(0) = 0          ! do nothing
             end                                  ! until a key is pressed




























                                       Page 26



          GAP Communications                                         CLACOM


          ClrBuf
          -----------------------------------------------------------------

          Purpose       Clears the Communications receive buffer.

                        ClrBuf(port)

                        SHORT port                COM Port Number

          Type          Procedure

          Description   Empties the  receive buffer  such that  any pending
                        characters are simply ignored.

          Return Value  None.

          Example       ClrBuf(0)                 ! clear Rec Buf (COM 1)


































                                       Page 27



          GAP Communications                                         CLACOM


          ComGetc
          -----------------------------------------------------------------

          Purpose       Retrieve a character from communications buffer.

                        ComGetc(port)

                        SHORT port                COM Port Number

          Type          Function - Returns SHORT

          Description   Checks  the   communications  receive   buffer  and
                        returns the  next character,  if any.  In order  to
                        distinguish between  a legitimate  character and  a
                        "no character"  condition, this  function returns a
                        SHORT even though a legitimate character is a BYTE.
                        If the  function does  not return  a -1, the return
                        value needs  to be  assigned to  a variable of type
                        BYTE if the character is to be passed to a function
                        that requires  a BYTE parameter (Gputc and ComPutc,
                        for instance).

          Return Value  Next character  in buffer  or -1  for no characters
                        waiting.

          Example       c = ComGetc(0)            ! get a char from remote

             keychr  BYTE
             retchr  SHORT
             comport SHORT

             comport = 0                          ! use COM 1

             retchr = ComGetc(comport)            ! get a char from remote

             if retchr NOT= -1                    ! anything there?
               keychr = retchr                    ! yes, truncate high byte
               Gputc(keychr)                      ! and display
             end












                                       Page 28



          GAP Communications                                         CLACOM


          ComGetd
          -----------------------------------------------------------------

          Purpose       Retrieve a  character  from  communications  buffer
                        with delay.

                        ComGetd(port,secs)

                        SHORT port                COM Port Number
                        SHORT secs                Number of seconds to wait

          Type          Function - Returns SHORT

          Description   This function  is the  same as ComGetc, except that
                        if there  are no  characters in the receive buffer,
                        it will wait for the number of seconds you specify.

          Return Value  Next character  in buffer  or -10  for time-out (no
                        characters to read).

          Example

             comport SHORT

             comport = 0                          ! use COM 1

             do while ComGetd(comport,2) = -10    ! wait 2 seconds
             end                                  ! for a character























                                       Page 29



          GAP Communications                                         CLACOM


          ComPutb
          -----------------------------------------------------------------

          Purpose       Sends a buffer of data out the communications port.

                        ComPutb(port,buffer,len)

                        SHORT port                COM Port Number
                        CSTRING buffer            Buffer containing data
                        SHORT len                 Number of bytes to send

          Type          Procedure

          Description   This function  will send  a user supplied buffer of
                        len bytes  out the communications port, one byte at
                        a time.

          Return Value  None.

          Example

             buffer    CSTRING(200)

             ComPutb(0,buffer,100)                ! Send 100 bytes to COM 1



























                                       Page 30



          GAP Communications                                         CLACOM


          ComPutc
          -----------------------------------------------------------------

          Purpose       Sends a  single character  out  the  communications
                        port.

                        ComPutc(port,ch)

                        SHORT port                COM Port Number
                        BYTE ch                   Character to send

          Type          Procedure

          Description   Will send a single character out the communications
                        port.

          Return Value  None.

          Example       ComPutc(0,13)             ! Send a Carriage Return

             keychr  BYTE
             retchr  SHORT
             comport SHORT

             comport = 0                          ! use COM 1

             retchr = GetKeyc                     ! Keyboard hit?

             if retchr NOT= -1                    ! anything there?
               if retchr < 256                    ! yes, if regular char
                 keychr = retchr                  ! truncate high byte
                 ComPutc(comport,keychr)          ! and send it to remote
               end
             end

















                                       Page 31



          GAP Communications                                         CLACOM


          ComPuts
          -----------------------------------------------------------------

          Purpose       Sends a string of characters out the communications
                        port.

                        ComPuts(port,str)

                        SHORT port                COM Port Number
                        CSTRING str               String to send

          Type          Procedure

          Description   Will  send   a  string   of  characters   out   the
                        communications port.  Note that unlike ComPutb, the
                        number of bytes to send is determined by the length
                        of  the   string.  Therefore  this  function  stops
                        sending characters  when  it  encounters  the  NULL
                        byte.

          Return Value  None.

          Example

             comport SHORT
             cstr    CSTRING(100)

             comport = 0                          ! use COM 1

             cstr = 'Send this String'            ! string to send
             ComPuts(comport,cstr)                ! send string to com port




















                                       Page 32



          GAP Communications                                         CLACOM


          CursorOff
          -----------------------------------------------------------------

          Purpose       Turns the local cursor off.

                        CursorOff()

          Type          Procedure

          Description   This function  is used  to turn  the cursor  on the
                        local monitor off.

          Return Value  None.

          Example       CursorOff()               ! turn the cursor off





          CursorOn
          -----------------------------------------------------------------

          Purpose       Turns the local cursor on.

                        CursorOn()

          Type          Procedure

          Description   This function  is used  to turn  the cursor  on the
                        local monitor on.

          Return Value  None.

          Example       CursorOn()                ! turn the cursor on
















                                       Page 33



          GAP Communications                                         CLACOM


          DclrTx
          -----------------------------------------------------------------

          Purpose       Clears the Transmit Buffer on DigiBoard.

                        DclrTx(port)

                        SHORT port                COM Port (Channel) Number

          Type          Procedure

          Description   When  using   a  DigiBoard  (Interface  is  set  to
                        DigiBoard or Int14/EBIOS), this function will clear
                        the Transmit  Buffer for  the specified port on the
                        DigiBoard.

          Return Value  None.

          Example       DclrTx(4)                 ! clear xmit buffer
































                                       Page 34



          GAP Communications                                         CLACOM


          DgtTxfree
          -----------------------------------------------------------------

          Purpose       Returns number  of  Free  Bytes  in  Digi  Transmit
                        Buffer.

                        DgtTxfree(port)

                        SHORT port                COM Port (Channel) Number

          Type          Function - Returns USHORT

          Description   When  using   a  DigiBoard  (Interface  is  set  to
                        DigiBoard or  Int14/EBIOS), this  function  returns
                        the number of free bytes in the Transmit Buffer for
                        the specified port on the DigiBoard.

          Return Value  None.

          Example

             freebytes   USHORT

             freebytes = DgtTxfree(4)             ! get free space



























                                       Page 35



          GAP Communications                                         CLACOM


          Dmodem
          -----------------------------------------------------------------

          Purpose       Initialize Digi  port to  baud, parity,  data,  and
                        stop bits

                        Dmodem(port,baud,parity,data,stop)

                        SHORT port        COM Port (Channel) Number
                        LONG baud         BPS rate
                        SHORT parity      0 = None, 1 = Odd, 2 = Even
                        SHORT data        6, 7, or 8 data bits
                        SHORT stop        1 or 2 stop bits

          Type          Procedure

          Description   Changes the current port settings on a DigiBoard to
                        the parity,  data bits,  stop bits,  and baud rate.
                        The port  number is  defined when initially setting
                        up the port with a call to DsetUp or Int14Set.

                        The port  parameters are  normally set  when  first
                        initializing  the  DigiBoard  port.  This  function
                        allows you  to change  those parameters  while "on-
                        line".

          Return Value  None.

          Example       Dmodem(4,2400,2,7,1)      ! E,7,1 - 2400 bps






















                                       Page 36



          GAP Communications                                         CLACOM


          DownLoad
          -----------------------------------------------------------------

          Purpose       Receives one or more files.

                        DownLoad(port,protocol,filename)

                        SHORT port                COM Port Number
                        SHORT protocol            Number of protocol to use
                        CSTRING filename          Name of file to download

          Type          Procedure

          Description   This function  allows you  to receive a file from a
                        remote  computer.  The  protocols  are  defined  as
                        follows:

                              0 = ASCII           3 = 1K Xmodem-G
                              1 = Xmodem          4 = Ymodem
                              2 = 1K Xmodem       5 = Ymodem-G


                        Filename is  a CSTRING  containing the  name of the
                        file to  download.  If  the  protocol  is  a  batch
                        protocol (Ymodem  or Ymodem-G)  then you may pass a
                        NULL string  (cstr = '') since the name of the file
                        will  be  supplied  by  the  remote  sender.  If  a
                        filename is passed, it will be ignored.

          Return Value  None.

          Example

             cstr  CSTRING(100)

             cstr = 'FILE.ZIP'                    ! receive a single file
             DownLoad(0,2,cstr)                   ! using 1K Xmodem
                                                             
                                                            _

             cstr = ''                            ! receive 1 or more files
             DownLoad(0,4,cstr)                   ! using Ymodem











                                       Page 37



          GAP Communications                                         CLACOM


          Drestore
          -----------------------------------------------------------------

          Purpose       Reset Modem attached to a DigiBoard Port.

                        Drestore()

                        SHORT port                COM Port (Channel) Number

          Type          Procedure

          Description   This function  simply  turns  off  the  handshaking
                        lines to  the modem.  It turns  DTR and RTS off and
                        disables Hardware Flow control. Should be used only
                        when using the DigiBoard or Int14/EBIOS Interface.

          Return Value  None.

          Example       Drestore(4)               ! Reset Modem
































                                       Page 38



          GAP Communications                                         CLACOM


          DsetUp
          -----------------------------------------------------------------

          Purpose       Initialize Digi  port to  baud, parity,  data,  and
                        stop bits.

                        DsetUp(base, port, channel, baud, parity
                               data, stop)

                        USHORT base       Memory Window
                        USHORT port       I/O Port
                        SHORT channel     Channel Number (port)
                        LONG baud         BPS rate
                        SHORT parity      0 = None, 1 = Odd, 2 = Even
                        SHORT data        6, 7, or 8 data bits
                        SHORT stop        1 or 2 stop bits

          Type          Function - Returns SHORT

          Description   When  using   a  Communications  Interface  set  to
                        DigiBoard, this  function initializes the specified
                        port (Channel)  on  the  DigiBoard.  The  DigiBoard
                        Interface is  a direct  link to  the  DigiBoard  (a
                        Device Driver  is not needed). In order to use this
                        interface, the  end user  must have already run the
                        DigiBoard Reset program called RESETDIG.EXE.

                        The base  address is  the high  memory address  the
                        DigiBoard uses  when communicating  with  the  host
                        computer.

                        Valid base addresses are:

                          C000          D000
                          C800          D800


                        The port  is the I/O port the DigiBoard is attached
                        to.

                        Valid ports are:

                          100           220
                          110           300
                          120           320
                          200





                                       Page 39



          GAP Communications                                         CLACOM


                        The channel  is the  Communications Port  to use on
                        the DigiBoard. This should be 0 - 15.

                        Note that  base and port are USHORTS. Because it is
                        difficult to  gather input  from an  end user  such
                        that the  result is  a  valid  hexadecimal  number,
                        these two  fields are  generally stored as strings.
                        You can  use  the  function  StrHex  to  convert  a
                        Hexadecimal String to an unsigned short.

          Return Value  0 = Successful.
                        1 = DigiBoard not Installed or RESETDIG.EXE
                            not run.
                        2 = DigiBoard not Responding.
                        3 = Invalid Parameter passed.
                        4 = DigiBoard EPROM is too old.

          Example

             ! set up 1st port on DigiBoard (Channel = 1)
             ! DigiBoard Memory Address = D800
             ! DigiBoard I/O Port = 320

             digiseg   USHORT
             digiport  USHORT
             cstr      CSTRING(12)

             cstr = 'D800'                        ! Base Address
             digiseg = StrHex(cstr)               ! as a number
             cstr = '320'                         ! I/O Port
             digiport = StrHex(cstr)              ! as a number

             if DsetUp(digiseg,digiport,1,38400,0,8,1)
               ShowError('Unable To Initialize DigiBoard')
             end
















                                       Page 40



          GAP Communications                                         CLACOM


          Dtr
          -----------------------------------------------------------------

          Purpose       Toggle the DTR line on or off.

                        Dtr(port,how)

                        SHORT port                COM Port Number
                        SHORT how                 0 = Turn DTR off
                                                  1 = Turn DTR on

          Type          Procedure

          Description   This routine  is used  to turn  the DTR line of the
                        communications port  on or  off.  Turning  DTR  off
                        while there  is a  carrier will  cause the modem to
                        drop carrier.  In order  to send  commands  to  the
                        modem, DTR needs to be on.

          Return Value  None.

          Example

             cstr    CSTRING(10)

             cstr = 'ATZ' & '<13>'        ! Modem Init String

             Dtr(0,1)                     ! turn DTR on,wake up modem
             ComPuts(0,cstr)              ! reset the modem






















                                       Page 41



          GAP Communications                                         CLACOM


          GetKeyc
          -----------------------------------------------------------------

          Purpose       Gets keyboard character and scan code.

                        GetKeyc()

          Type          Function - Returns SHORT

          Description   This is the main keyboard input routine. It returns
                        the keyboard  character or if the key struck was an
                        extended key,  it will  return a unique code. These
                        codes are  described in  Appendix A.  This function
                        should be  used when  designing terminal  emulation
                        software, BBS  software or  any software  where you
                        will be  checking the  local keyboard  and the  Com
                        Port for  key presses.  Clarion's ASK  and  KEYCODE
                        functions cannot  be  used  since  Clarion  re-maps
                        extended keys  and some control keys. Any character
                        in the ASCII range of 0 to 255 is a valid character
                        and can  be sent  out the Com Port, however Clarion
                        re-maps some  of  these  characters  and  does  not
                        return their true byte value.

                        If the  return value  is greater than 255, then the
                        key that  was pressed is an Extended Key (i.e., F1,
                        Up-Arrow,  PgUp,   Home,  etc).  The  Extended  Key
                        corresponds to  the Keyboard  Scan codes  with  the
                        value 256 added.

          Return Value  ASCII code for the key pressed or a unique code for
                        extended keys.

          Example

             retchr  SHORT

             retchr = GetKeyc()                   ! get a keyboard char

             if retchr > 255                      ! Extended Key
               case retchr                        ! which one
                 of 278  ! Alt-U, Upload a File
                 of 288  ! Alt-D, Download a File
                 of 369  ! Alt-F10, activate Menu
               end
             end





                                       Page 42



          GAP Communications                                         CLACOM


          GetScrn
          -----------------------------------------------------------------

          Purpose       Copies Physical Screen to Clarion Screen Buffer.

                        GetScrn()

          Type          Procedure

          Description   Clarion keeps  a backup copy of the physical screen
                        in a  buffer. Whenever  you send  something to  the
                        screen by  either opening a Window, a Menu, or what
                        have  you,  Clarion  performs  two  operations:  it
                        updates the physical screen and its screen buffer.

                        The screen  output routines  in CLACOM  (Gputc  and
                        Gputs)  write   directly  to  the  physical  screen
                        memory. Clarion,  therefore, doesn't  know that the
                        screen has  been written to. When you open a Window
                        or a  Menu, Clarion  will re-draw  the screen  with
                        whatever happens  to be  in its  Screen Buffer  and
                        then open  your Window.  What Clarion  puts on  the
                        screen will not necessarily be what you see on your
                        physical screen.  Clarion only  knows about what it
                        wrote to  the physical  screen.  It  knows  nothing
                        about what  an outside  function might  have put on
                        the screen.

                        If you  are using  the CLACOM  routines to write to
                        the screen  and you  need to open a Clarion Window,
                        activate a  Menu, or  otherwise write  to the local
                        screen using  a Clarion  function, you need to call
                        GetScrn before  making your  Clarion call.  GetScrn
                        will copy  the contents  of the  Physical Screen to
                        the  Clarion   Screen  Buffer.  This  will  prevent
                        Clarion from  overwriting the  physical screen with
                        data that no longer belongs there.

          Return Value  None.












                                       Page 43



          GAP Communications                                         CLACOM


          Example

             keychr  BYTE
             retchr  SHORT

             retchr = GetKeyc()                   ! Keyboard hit?

             if retchr = -1                       ! nothing there
               goto getrmt                        ! check remote
             end

             keychr = retchr                      ! strip high byte if set

             if retchr < 256                      ! if not a scan code
               ComPutc(0,keychr)                  ! send to com port
               goto getrmt                        ! and check remote
             end

             ! Keyboard key was an Extended key. Check if special key

             ! First though, it is likely that we will be doing something
             ! that will use Clarion to write to the Screen (open Window,
             ! Menu, etc). If so, we have to read the physical screen and
             ! update Clarion's Screen Buffer. This is because Clarion
             ! doesn't know that our ANSI driver has been writing to the
             ! screen. If we don't do this, Clarion will erase whatever is
             ! on the screen right now.

             GetScrn()                    ! update Clarion Screen Buffer






















                                       Page 44



          GAP Communications                                         CLACOM


             ! Note that we already know the key is an extended key so we
             ! are only checking the low byte of the key (same as
             ! subtracting 256 from the return value).

             case keychr                  ! get special keys
               of 22                      ! Alt-U, Upload A File
                 if online = 0            ! if no carrier, you can't upload

                   ! This is one reason for GetScrn. Remove the call to
                   ! GetScrn and watch what happens when following window
                   ! is opened.

                   Open(NotOnLine)        ! Tell um can't upload
                   bell()                 ! Make noise
                   Beep(0,300)            ! Wait 3 seconds
                   Close(NotOnLine)       ! Close Can't Upload Screen
                 else                     ! otherwise, upload away
                   UpFile
                 end
             end































                                       Page 45



          GAP Communications                                         CLACOM


          GetZmodem
          -----------------------------------------------------------------

          Purpose       Receives 1 or more files using the Zmodem Protocol.

                        GetZmodem(port)

                        SHORT port                COM Port Number

          Type          Procedure

          Description   This function  allows you  to receive  one or  more
                        files using  Zmodem. The  files will  be placed  in
                        whatever directory  the program happens to be in at
                        the time  of the  call. You may want to use SETPATH
                        to change into a work directory prior to the call.

          Return Value  None.

          Example       GetZmodem(0)              ! Receive using Zmodem































                                       Page 46



          GAP Communications                                         CLACOM


          Gputc
          -----------------------------------------------------------------

          Purpose       Sends a single character to local screen.

                        Gputc(ch)

                        BYTE ch                   Character to send

          Type          Procedure

          Description   This is one of the main output routines. It is part
                        of the ANSI driver. It will send a single character
                        to the local screen.

          Return Value  None.

          Example       Gputc(12)                 ! Clear the Screen

             retchr  SHORT
             keychr  BYTE

             retchr = GetKeyc()                   ! Keyboard hit?

             if retchr NOT= -1                    ! if something there
               keychr = retchr                    ! truncate high byte
               Gputc(keychr)                      ! and display it
             end























                                       Page 47



          GAP Communications                                         CLACOM


          Gputs
          -----------------------------------------------------------------

          Purpose       Sends a string of characters to local screen.

                        Gputs(str)

                        CSTRING str               String to send

          Type          Procedure

          Description   This is one of the main output routines and is part
                        of the  ANSI driver.  It  will  send  a  string  of
                        characters to the local screen.

          Return Value  None.

          Example

             cstr  CSTRING(100)

             cstr = 'This is a string of characters'

             Gputs(cstr)                          ! Display locally
             ComPuts(0,cstr)                      ! and to remote

             ! this example embeds the CR/LF pair at the beginning
             ! and end of the string

             cstr = '<13,10>' & 'This is a string of characters' &
          '<13,10>'

             Gputs(cstr)                          ! Display locally


















                                       Page 48



          GAP Communications                                         CLACOM


          InitAnsi
          -----------------------------------------------------------------

          Purpose       Initialize ANSI driver.

                        InitAnsi(port,row,col,color)

                        SHORT port        COM Port Number
                        BYTE row          Number of Rows on Screen
                        BYTE col          Number of Columns on Screen
                        BYTE color        Default Color to use

          Type          Procedure

          Description   This function  sets up  the ANSI  driver so that it
                        knows the maximum number of Rows and Columns on the
                        Screen and the default color to use when displaying
                        characters. This  function must  be called prior to
                        using the  output routines  Gputc and  Gputs. Since
                        the ANSI driver writes directly to Video Memory, it
                        is imperative  that this function be called so that
                        it can  set internal  variables that tells it where
                        the cursor  is, the  color attribute  to  use  when
                        displaying characters  and the  Segment address  of
                        Video Memory.

                        You should call this function anytime the Screen is
                        changed in size (i.e., from 25 to 43 line mode).

                        The ANSI  driver always  protects the bottom row of
                        the screen.  In other words, it will not allow text
                        to be  written there  using Gputc  or Gputs. If you
                        need to  write to  the bottom  screen row,  use the
                        Clarion SHOW function.

                        The color parameter is a standard IBM color code in
                        the  range  of  0  to  255.  The  Color  codes  are
                        described in  the Clarion Language Reference Manual
                        in the Video and Keyboard Chapter.

                        You must  pass the  COM port  number that  the ANSI
                        driver will  be associated  with. The  ANSI  Cursor
                        Position Report (CPR) is issued whenever the driver
                        receives a  Device Status Report (DSR) command. The
                        CPR sequence  is sent out the COM port. Since there
                        is only  one screen and one ANSI driver, the driver
                        must know  which port to use. The DSR/CPR sequences




                                       Page 49



          GAP Communications                                         CLACOM


                        are  generally   only  used   by  BBS  programs  to
                        determine if the caller has ANSI capability.

          Return Value  None.

          Example

             MaxRows  SHORT
             MaxCols  SHORT

             MaxRows = ROWS()                  ! Get Max Number of Rows
             MaxCols = COLS()                  ! Get Max Number of Columns

             SetCursor(1,1)                    ! Cursor to top of screen
             InitAnsi(0,MaxRows,MaxCols,14)    ! Initialize ANSI driver




































                                       Page 50



          GAP Communications                                         CLACOM


          InitPort
          -----------------------------------------------------------------

          Purpose       Initialize port  to baud,  data, parity,  and  stop
                        bits.

                        InitPort(port,baud,parity,data,stop)

                        SHORT port        COM Port Number
                        LONG baud         BPS rate
                        SHORT parity      0 = None, 1 = Odd, 2 = Even
                        SHORT data        6, 7, or 8 data bits
                        SHORT stop        1 or 2 stop bits

          Type          Function - Returns SHORT

          Description   Sets the  communications port  to the  parity, data
                        bits, stop  bits, and baud rate. The port number is
                        defined when  initially setting  up the port with a
                        call to SetPort.

                        This  function   should  only   be  used  when  the
                        Communications Interface  is set to Standard. Don't
                        call when interfacing with a DigiBoard.

          Return Value  0 = Successful.
                        1 = Port Not Initialized.
                        2 = Invalid Parameter.

          Example

             if InitPort(0,38400,0,8,1)   ! Initialize to N,8,1 - 38400 bps
               ShowError('Unable To Initialize Port')
             end

















                                       Page 51



          GAP Communications                                         CLACOM


          Int14Set
          -----------------------------------------------------------------

          Purpose       Initialize Digi  port to  baud, parity,  data,  and
                        stop bits.

                        DsetUp(channel,baud,parity,data,stop)

                        SHORT channel     Channel Number (port)
                        LONG baud         BPS rate
                        SHORT parity      0 = None, 1 = Odd, 2 = Even
                        SHORT data        6, 7, or 8 data bits
                        SHORT stop        1 or 2 stop bits

          Type          Function - Returns SHORT

          Description   When  using   a  Communications  Interface  set  to
                        Int14/EBIOS,   this    function   initializes   the
                        specified port  (Channel) on  the  DigiBoard.  This
                        interface requires  that  the  end  user  have  the
                        DigiBoard supplied  Universal DOS  Driver installed
                        as a TSR.

                        The channel  is the  Communications Port  to use on
                        the DigiBoard. This should be 4 - 19.

          Return Value  0 = Successful.
                        1 = Device Driver not installed or DigiBoard not
                            installed.
                        2 = EBIOS not configured.
                        3 = Invalid Parameter passed.

          Example

             ! set up 1st port on DigiBoard (Channel = 4)

             if Int14Set(4,38400,0,8,1)
               ShowError('Unable To Initialize DigiBoard')
             end












                                       Page 52



          GAP Communications                                         CLACOM


          Iscd
          -----------------------------------------------------------------

          Purpose       Check for Carrier on the Communications Port.

                        Iscd(port)

                        SHORT port                COM Port Number

          Type          Function - Returns SHORT

          Description   This function allows you to test the communications
                        port for a remote carrier signal.

          Return Value  Returns 0  if there is no carrier and 1 if there is
                        a carrier.

          Example

             if Iscd(0)                           ! is there a carrier?
               online = 1
               show(MaxRows,MaxCols - 7,' OnLine')
             else
               online = 0
               show(MaxRows,MaxCols - 7,'OffLine')
             end

























                                       Page 53



          GAP Communications                                         CLACOM


          ModemPuts
          -----------------------------------------------------------------

          Purpose       Sends a Command String to a Modem.

                        ModemPuts(port,str)

                        SHORT port                COM Port Number
                        CSTRING str               String to send

          Type          Procedure

          Description   Will  send   a  string   of  characters   out   the
                        communications port.  This  function  is  generally
                        used to  send commands  to a modem. It is identical
                        to ComPuts  except that it interprets and acts upon
                        certain characters.

                        The special characters are:

                              ^M -  Send a Carriage Return

                              ~  -  Tilde. Pause for 1/2 second

                        Note that  the special  characters are  not sent to
                        the modem.  Also note  that in order for a modem to
                        accept commands,  the modem  must be "offline" (not
                        connected to  a remote modem) and DTR must be set :
                        Dtr(1).

          Return Value  None.

          Example

             cstr  CSTRING(100)

             cstr = 'ATZ^M~~'                     ! Modem Reset String

             ! The above string will send the Modem Reset String followed
             ! by a Carriage Return. It will wait 1 second after sending
             ! the string.

             ModemPuts(0,cstr)                    ! Send Modem Command








                                       Page 54



          GAP Communications                                         CLACOM


          ModemStat
          -----------------------------------------------------------------

          Purpose       Returns Status of the attached Modem.

                        ModemStat(port)

                        SHORT port                COM Port Number

          Type          Function - Returns BYTE

          Description   Returns the value of the Modem Status Register.

          Return Value  None.

          Example

             modstat BYTE

             modstat = ModemStat(0)               ! get Modem Status

             if BAND(Modstat,080h)                ! check for Carrier
               online = 1                         ! got one, set flag
             else
               online = 0                         ! no carrier, reset flag
             end

























                                       Page 55



          GAP Communications                                         CLACOM


          PosCursor
          -----------------------------------------------------------------

          Purpose       Restore ANSI Driver Cursor Position.

                        PosCursor()

          Type          Procedure

          Description   When opening  a window and then closing it, Clarion
                        does not  put the cursor back where it was prior to
                        opening the window. This doesn't cause any problems
                        because the  ANSI driver maintains its own internal
                        cursor position.  However, the  screen will  look a
                        bit strange  if the  cursor  is  "hanging"  in  the
                        middle of  the screen  when it  should be on row 2,
                        column 10.

          Return Value  None.

          Example       PosCursor()       ! Put Cursor back where it was






























                                       Page 56



          GAP Communications                                         CLACOM


          ResetPort
          -----------------------------------------------------------------

          Purpose       Restores the Communications port.

                        ResetPort(port)

                        SHORT port                COM Port Number

          Type          Procedure

          Description   This function  must be  called prior to exiting the
                        program or  anytime you  are finished  with the Com
                        Port. It  restores the interrupt vector used by the
                        Standard Communications routines.

                        It is  imperative  that  when  using  the  Standard
                        Interface you call this function when you no longer
                        wish  to  access  the  Serial  Port.  The  Standard
                        Interface sets  up an interrupt vector for the port
                        and if this vector is not restored prior to exiting
                        your program, the computer will ultimately crash.

                        This  function   should  only   be  used  when  the
                        Communications Interface  is set to Standard. Don't
                        call when interfacing with a DigiBoard.

          Return Value  None.

          Example       ResetPort(0)              ! Reset COM 1





















                                       Page 57



          GAP Communications                                         CLACOM


          RestCbreak
          -----------------------------------------------------------------

          Purpose       Restores the Ctrl-Break vector.

                        RestCbreak()

          Type          Procedure

          Description   This function  must be  called prior to exiting the
                        program. It  restores the  interrupt vector used by
                        the Ctrl-Break  routine. If you set up a Ctrl-Break
                        handler at  the  beginning  of  your  program,  you
                        should  call   this  function   from   a   SHUTDOWN
                        procedure. Setting  up a SHUTDOWN procedure insures
                        that the  Ctrl-Break vector  is restored  prior  to
                        program termination.

          Return Value  None.

          Example       RestCbreak()      ! restore Ctrl-Break vector






























                                       Page 58



          GAP Communications                                         CLACOM


          Rts
          -----------------------------------------------------------------

          Purpose       Toggle the RTS line on or off.

                        Rts(port,how)

                        SHORT port                COM Port Number
                        SHORT how                 0 = Turn RTS off
                                                  1 = Turn RTS on

          Type          Procedure

          Description   This routine  is used  to turn  the Request To Send
                        line of  the communications port on or off. Turning
                        RTS off  (providing  the  modem  supports  hardware
                        handshaking) tells  the modem  to stop sending data
                        to the  computer. It is typically toggled off while
                        writing a buffer of data to a disk.

          Return Value  None.

          Example       Rts(0,0)                  ! Turn RTS off




























                                       Page 59



          GAP Communications                                         CLACOM


          Rxempty
          -----------------------------------------------------------------

          Purpose       To check if there are any characters in the receive
                        buffer.

                        Rxempty(port)

                        SHORT port                COM Port Number

          Type          Function - Returns SHORT

          Description   This function  checks  the  communications  receive
                        buffer to  see if  there are any characters waiting
                        to be read.

          Return Value  Returns 1  if buffer  is  empty,  0  if  there  are
                        characters waiting to be read.

          Example

             while Rxempty(0)             ! nothing happening
             end                          ! wait till something to read




























                                       Page 60



          GAP Communications                                         CLACOM


          SendBreak
          -----------------------------------------------------------------

          Purpose       Sends a Break Signal to Modem.

                        SendBreak(port)

                        SHORT port                COM Port Number

          Type          Procedure

          Description   Will  send  a  Break  Signal  to  the  Modem.  This
                        function is  most often used with high speed modems
                        that have their own transmit buffer and you wish to
                        clear the buffer. These modems can be configured to
                        empty their buffer upon receipt of a break signal.

                        Note that  some modems  do not  react too well to a
                        break signal. Whether or not to send a break to the
                        modem so  that you  can clear  its transmit  buffer
                        should be a configuration option.

          Return Value  None.

          Example       SendBreak(0)              ! Send a Break to Modem


























                                       Page 61



          GAP Communications                                         CLACOM


          SendZmodem
          -----------------------------------------------------------------

          Purpose       Sends one or more files using Zmodem.

                        SendZmodem(port,filename)

                        SHORT port                COM Port Number
                        CSTRING filename          Name of file to upload

          Type          Procedure

          Description   This function  allows you to send one or more files
                        to a remote computer using the Zmodem Protocol.

                        Filename is  a CSTRING  containing the  name of the
                        file  to   upload.  It  may  contain  a  Wild  Card
                        Specification to send more than one file at a time.

          Return Value  None.

          Example

             cstr  CSTRING(100)

             cstr = 'FILE.ZIP'                    ! send a single file
             SendZmodem(0,cstr)

             cstr = '*.ZIP'                       ! send all the ZIP files
             SendZmodem(0,cstr)





















                                       Page 62



          GAP Communications                                         CLACOM


          SetCbreak
          -----------------------------------------------------------------

          Purpose       Initializes the Ctrl-Break vector.

                        SetCbreak()

          Type          Procedure

          Description   To trap Ctrl-C and Ctrl-Break, this function should
                        be called to set up an interrupt service routine to
                        trap these  two keys.  It is  imperative  that  the
                        program not  exit before calling RestCbreak so that
                        the interrupt vector can be restored.

                        When using the Standard Communications Interface, a
                        Ctrl-Break vector  must be  installed to  prevent a
                        user from  breaking  out  of  your  program  before
                        you've had  a chance  to restore the Communications
                        Interrupt vector.

          Return Value  None.

          Example       SetCbreak()               ! set up Ctrl-Break ISR



























                                       Page 63



          GAP Communications                                         CLACOM


          SetPort
          -----------------------------------------------------------------

          Purpose       Initialize the Communications Port.

                        SetPort(irq,base,port)

                        SHORT irq                 Port IRQ to use
                        SHORT base                Port Base Address to use
                        SHORT port                Com Port Number

          Type          Function - Returns SHORT

          Description   This is  the port  initialization routine that must
                        be called  when using  the Standard  Interface.  It
                        must be called prior to any port I/O calls.

                        IRQ is  the Interrupt Request number to use for the
                        port. Base Address is the address where the port is
                        located. Port  is the COM port number, where COM1 =
                        0, COM2  = 1, COM3 = 2, and COM4 = 3. For COM 1 and
                        COM 2,  you may  simply pass  0 as the IRQ and Base
                        address since  the defaults for these ports will be
                        used.

                        Note that  the Communications  Routines always  use
                        hardware handshaking. This means that if CTS is not
                        active, the  output routines  will not  be able  to
                        send a  character  out  the  serial  port.  CTS  is
                        normally controlled  by a  Modem, however  when not
                        using a  modem, the  serial cable  must be wired so
                        that CTS  on one  end of  the connection is tied to
                        RTS on  the other end. See Appendix B for a diagram
                        of a NULL Modem cable.

          Return Value  0 = successful.
                        1 = No UART found at Port Address.
                        2 = Clear To Send (CTS) is not active.

          Example

             ! Set Up Port on COM1

             if SetPort(0,0,0)
               ShowError('Unable To Initialize Port')
             end





                                       Page 64



          GAP Communications                                         CLACOM


          StrHex
          -----------------------------------------------------------------

          Purpose       Converts a Hexadecimal string to an Unsigned Short.

                        StrHex(hexstring)

                        CSTRING hexstring String containing Hex digits

          Type          Function - Returns USHORT

          Description   This function  will  convert  a  string  containing
                        hexadecimal digits  and return  the value  of  that
                        string as  an unsigned short. It is most often used
                        to convert Memory Addresses stored as a string to a
                        number  that   can  be   utilized   by   the   port
                        initialization routines.

          Return Value  0 if  string could  not be  converted, number if it
                        could.

          Example

             cstr    CSTRING(100)
             hexnum  USHORT

             cstr = 'D800'                        ! Base Address
             hexnum = StrHex(cstr)                ! as a number























                                       Page 65



          GAP Communications                                         CLACOM


          StrWord
          -----------------------------------------------------------------

          Purpose       Check if one string contains another string.

                        StrWord(srcstring,substring)

                        CSTRING srcstring         String to search
                        CSTRING substring         String to search for

          Type          Function - Returns SHORT

          Description   Clarion's INSTRING  function doesn't work very well
                        with C  strings (in  fact, it doesn't work at all).
                        The terminating  NULL seems  to be included as part
                        of the search value.

                        StrWord will  search for  a string  to see if it is
                        contained within  another string. Both strings must
                        be of  type CSTRING.  If the larger string contains
                        the smaller  string, the  position  in  the  larger
                        string where  the smaller  string  begins  will  be
                        returned.

                        Note that  the strings  are compared without regard
                        to case.

          Return Value  0 if  substring not  found, otherwise  position  in
                        source string where the substring starts.

          Example

             srcstring CSTRING(100)
             substring CSTRING(10)

             scrstring = 'This is a string'
             substring = 'string'

             if StrWord(srcstring,substring)
               ! srcstring contains substring
             else
               ! substring not found
             end








                                       Page 66



          GAP Communications                                         CLACOM


          Timer
          -----------------------------------------------------------------

          Purpose       Pauses for the number of "ticks" specified.

                        Timer(ticks)

                        SHORT ticks       Number of timer ticks to pause

          Type          Procedure

          Description   This function  allows you  to pause  all processing
                        for the  specified  number  of  ticks.  It  is  in-
                        sensitive to processor speed.

                        The function  simply delays  the number  of "ticks"
                        indicated by  the passed  parameter. Each  tick  is
                        1/18 of a second (or 55 milliseconds).

          Return Value  None.

          Example       Timer(18)                 ! pause for 1 second





























                                       Page 67



          GAP Communications                                         CLACOM


          UpLoad
          -----------------------------------------------------------------

          Purpose       Sends one or more files.

                        UpLoad(port,protocol,filename)

                        SHORT port                Com Port Number
                        SHORT protocol            Number of protocol to use
                        CSTRING filename          Name of file to upload

          Type          Procedure

          Description   This function allows you to send a file to a remote
                        computer. The protocols are defined as follows:

                              0 = ASCII           3 = 1K Xmodem-G
                              1 = Xmodem          4 = Ymodem
                              2 = 1K Xmodem       5 = Ymodem-G


                        Filename is  a CSTRING  containing the  name of the
                        file to upload. If the protocol is a batch protocol
                        (Ymodem or  Ymodem-G) then you may pass a Wild Card
                        Specification to send more than one file at a time.

          Return Value  None.

          Example

             cstr  CSTRING(100)

             cstr = 'FILE.ZIP'                    ! send a single file
             UpLoad(0,2,cstr)                     ! using 1K Xmodem

             cstr = '*.ZIP'                       ! send all the ZIP files
             UpLoad(0,4,cstr)                     ! using Ymodem














                                       Page 68



          GAP Communications                                         CLACOM






          Appendix A


          GetKeyc obtains  keyboard input  by making  calls to the Computer
          BIOS. The  BIOS translates keyboard scan codes into unique codes.
          Any code returned by GetKeyc that is less than or equal to 127 is
          a regular  ASCII character.  Codes in the range of 128 to 255 are
          IBM enhanced  ASCII characters.  These codes are returned "as is"
          (no translations are performed upon them).

          Key Codes  greater than 255 present a problem. These are extended
          keys and include the function keys, cursor keys, and the Ctrl and
          Alt key  combinations. The  BIOS returns  the scan  code of these
          keys. The  problem is  that the scan code can lie in the range of
          ASCII characters (0 through 255).

          In order to distinguish between a displayable ASCII character and
          an extended  key (F1,  Home, PgDn,  Alt-Equal, etc), GetKeyc adds
          256 to the key code returned by the BIOS.

          The following  tables show  the extended  key codes  as  well  as
          Control  Key   combinations  (which   are  used   extensively  in
          communications).
























                                       Page 69



          GAP Communications                                         CLACOM


          Control Keys and Extended Keys in Numerical Order:

            Ctrl-A      1       Alt-S        287      Shift-F9          348
            Ctrl-B      2       Alt-D        288      Shift-F10         349
            Ctrl-C      3       Alt-F        289      Ctrl-F1           350
            Ctrl-D      4       Alt-G        290      Ctrl-F2           351
            Ctrl-E      5       Alt-H        291      Ctrl-F3           352
            Ctrl-F      6       Alt-J        292      Ctrl-F4           353
            Ctrl-G      7       Alt-K        293      Ctrl-F5           354
            Backspace   8       Alt-L        294      Ctrl-F6           355
            Ctrl-H      8       Alt-Z        300      Ctrl-F7           356
            Ctrl-I      9       Alt-X        301      Ctrl-F8           357
            Tab         9       Alt-C        302      Ctrl-F9           358
            Ctrl-J      10      Alt-V        303      Ctrl-F10          359
            LineFeed    10      Alt-B        304      Alt-F1            360
            Ctrl-K      11      Alt-N        305      Alt-F2            361
            Ctrl-L      12      Alt-M        306      Alt-F3            362
            Ctrl-M      13      F1           315      Alt-F4            363
            Enter       13      F2           316      Alt-F5            364
            Ctrl-N      14      F3           317      Alt-F6            365
            Ctrl-O      15      F4           318      Alt-F7            366
            Ctrl-P      16      F5           319      Alt-F8            367
            Ctrl-Q      17      F6           320      Alt-F9            368
            Ctrl-R      18      F7           321      Alt-F10           369
            Ctrl-S      19      F8           322      Ctrl-PrintScreen  370
            Ctrl-T      20      F9           323      Ctrl-CursorLeft   371
            Ctrl-U      21      F10          324      Ctrl-CursorRight  372
            Ctrl-V      22      Home         327      Ctrl-End          373
            Ctrl-W      23      CursorUp     328      Ctrl-PgDn         374
            Ctrl-X      24      PgUp         329      Ctrl-Home         375
            Ctrl-Y      25      CursorLeft   331      Alt-1             376
            Ctrl-Z      26      CursorRight  333      Alt-2             377
            Escape      27      End          335      Alt-3             378
            BackTab     271     CursorDown   336      Alt-4             379
            Alt-Q       272     PgDn         337      Alt-5             380
            Alt-W       273     Insert       338      Alt-6             381
            Alt-E       274     Delete       339      Alt-7             382
            Alt-R       275     Shift-F1     340      Alt-8             383
            Alt-T       276     Shift-F2     341      Alt-9             384
            Alt-Y       277     Shift-F3     342      Alt-0             385
            Alt-U       278     Shift-F4     343      Alt-Hyphen        386
            Alt-I       279     Shift-F5     344      Alt-Equal         387
            Alt-O       280     Shift-F6     345      Ctrl-PgUp         388
            Alt-P       281     Shift-F7     346                           
            Alt-A       286     Shift-F8     347                           






                                       Page 70



          GAP Communications                                         CLACOM


          Control Keys and Extended Keys in Alphabetical Order:

            Alt-0       385     Alt-V        303      Ctrl-T             20
            Alt-1       376     Alt-W        273      Ctrl-U             21
            Alt-2       377     Alt-X        301      Ctrl-V             22
            Alt-3       378     Alt-Y        277      Ctrl-W             23
            Alt-4       379     Alt-Z        300      Ctrl-X             24
            Alt-5       380     Backspace      8      Ctrl-Y             25
            Alt-6       381     BackTab      271      Ctrl-Z             26
            Alt-7       382     Ctrl-A         1      CursorDown        336
            Alt-8       383     Ctrl-B         2      CursorLeft        331
            Alt-9       384     Ctrl-C         3      CursorRight       333
            Alt-A       286     Ctrl-CLeft   371      CursorUp          328
            Alt-B       304     Ctrl-CRight  372      Delete            339
            Alt-C       302     Ctrl-D         4      End               335
            Alt-D       288     Ctrl-E         5      Enter              13
            Alt-E       274     Ctrl-End     373      Escape             27
            Alt-Equal   387     Ctrl-F         6      F1                315
            Alt-F       289     Ctrl-F1      350      F10               324
            Alt-F1      360     Ctrl-F10     359      F2                316
            Alt-F10     369     Ctrl-F2      351      F3                317
            Alt-F2      361     Ctrl-F3      352      F4                318
            Alt-F3      362     Ctrl-F4      353      F5                319
            Alt-F4      363     Ctrl-F5      354      F6                320
            Alt-F5      364     Ctrl-F6      355      F7                321
            Alt-F6      365     Ctrl-F7      356      F8                322
            Alt-F7      366     Ctrl-F8      357      F9                323
            Alt-F8      367     Ctrl-F9      358      Home              327
            Alt-F9      368     Ctrl-G         7      Insert            338
            Alt-G       290     Ctrl-H         8      LineFeed           10
            Alt-H       291     Ctrl-Home    375      PgDn              337
            Alt-Hyphen  386     Ctrl-I         9      PgUp              329
            Alt-I       279     Ctrl-J        10      Shift-F1          340
            Alt-J       292     Ctrl-K        11      Shift-F10         349
            Alt-K       293     Ctrl-L        12      Shift-F2          341
            Alt-L       294     Ctrl-M        13      Shift-F3          342
            Alt-M       306     Ctrl-N        14      Shift-F4          343
            Alt-N       305     Ctrl-O        15      Shift-F5          344
            Alt-O       280     Ctrl-P        16      Shift-F6          345
            Alt-P       281     Ctrl-PgDn    374      Shift-F7          346
            Alt-Q       272     Ctrl-PgUp    388      Shift-F8          347
            Alt-R       275     Ctrl-PrtScr  370      Shift-F9          348
            Alt-S       287     Ctrl-Q        17      Tab                 9
            Alt-T       276     Ctrl-R        18                           
            Alt-U       278     Ctrl-S        19                           






                                       Page 71



          GAP Communications                                         CLACOM


          Appendix B


          Most  of   the  Null   Modem  connectors   and  cables  that  are
          commercially   available    are   wired    incorrectly.    Sounds
          unbelievable,  but   true.  They   are  wired  using  yesterday's
          technology.

          Modern day  modems are  intelligent devices.  They are capable of
          telling the  Host Computer when to stop sending data and are able
          to determine  when the  computer needs  to have  data sent  to it
          temporarily suspended.  This concept  is known  as Hardware  Flow
          Control (CTS/RTS checking).

          CLACOM was  written  with  Hardware  Flow  Control  in  mind.  No
          characters will be sent to the communications port if the port is
          unable to  accept new  characters. This prevents loss of data and
          insures a reliable connection.

          Most NULL  Modems are  wired with the CTS/RTS lines either always
          off or always on.

          If you  are hardwiring  computers together  via a NULL Modem, you
          will  probably   have  to  change  some  of  the  wiring  on  the
          connectors. You  can either  make your own NULL Modem or purchase
          one. If  you purchase  one, be  sure  that  you  can  remove  the
          connector shields to gain access to the wiring.

          The following diagram shows a properly wired NULL Modem:




                  SCREEN NOT AVAILABLE IN TEXT BASED DOCUMENTATION
                                 SEE PRINTED MANUAL
















                                       Page 72



          GAP Communications                                         CLACOM




          Index


          Ansi driver    5, 19, 20, 22, 24, 44, 47, 48, 56
            Initializing 14, 24, 49
          Asciidel  23
          ASK  42
          Base Address   10, 64
          Baud Rate 5, 36, 39, 51, 52, 64
          Channel   10, 11, 39, 40, 52
          Characters
            Sending to com port    17, 24, 31
            Sending to local screen     17, 24, 47
          CkeyPress 24, 26
          Clarion
            ASK     42
            Color   49
            CSTRING 25, 32, 37, 40, 41, 48, 54, 62, 65, 66, 68
            Cursor  56
            INSTRING     66
            KEYCODE 12, 42
            Overlays     8
            ROVERLAY.EXP 8
            Screen  56
            Screen Buffer     20, 43
            SHOW    49
            Strings 66
            TYPE    22
            Type Checking     25
          ClrBuf    24, 27
          Color     49
          ComGetc   19, 24, 28
          ComGetd   24, 29
          Communications
            Base address 14, 64
            Baud rates   5, 14, 64
            Carrier 53
            DigiBoard    9, 14, 51, 57
            FIFO buffers 5, 14
            Initializing 14, 36, 39, 51, 52, 64
            Input   28, 29, 60
            Interface    9, 51, 57
            Interrupt    8, 14, 57
            IRQ     64
            Output  30, 31, 32, 54
            Port    9, 64



                                       Page 73



          GAP Communications                                         CLACOM


          ComPutb   24, 30
          ComPutc   20, 24, 31
          Computs   20, 24, 32
          CSTRING   25, 32, 37, 40, 41, 48, 54, 62, 65, 66, 68
          Ctrl-Break handler  8, 58, 63
          CTS  64
          Cursor    24, 33, 56
          CursorOff 24, 33
          CursorOn  24, 33
          DclrTx    24, 34
          Delaying  67
          DgtTxfree 24, 35
          DigiBoard 9, 51, 57
            Channel 10, 11, 39, 40, 52
            Initializing Port 14, 36, 39, 52
            Resetting Modem   38
            Transmit Buffer   34
              Free Space 35
          Distribution files  6
          Dmodem    24, 36
          DownLoad  24, 37
          Downloading Files   11, 37, 46
          Drestore  24, 38
          DsetUp    14, 24, 36, 39
          Dtr  24, 41
          Files
            Downloading  11, 37, 46
            Uploading    11, 62, 68
          Functions
            CkeyPress    26
            ClrBuf  27
            ComGetc 19, 28
            ComGetd 29
            ComPutb 30
            ComPutc 20, 31
            ComPuts 20, 32
            CursorOff    33
            CursorOn     33
            DclrTx  34
            DgtTxfree    35
            Dmodem  36
            DownLoad     37
            Drestore     38
            DsetUp  14, 36, 39
            Dtr     41
            GetKeyc 12, 42, 69
            GetScrn 43
            GetZmodem    46



                                       Page 74



          GAP Communications                                         CLACOM


            Gputc   19, 43, 47, 49
            Gputs   19, 43, 48, 49
            InitAnsi     14, 49
            InitPort     14, 51
            INSTRING     66
            Int14Set     14, 36, 52
            Iscd    53
            ModemPuts    54
            ModemStat    55
            PosCursor    56
            ResetPort    57
            RestCbreak   58
            Rts     59
            Rxempty 60
            SendBreak    61
            SendZmodem   62
            SetCbreak    63
            SETPATH 46
            SetPort 14, 51, 64
            SHOW    49
            SHUTDOWN     58
            StrHex  40, 65
            StrWord 66
            Timer   67
            UpLoad  68
          GetKeyc   12, 24, 42, 69
          GetScrn   24, 43
          GetZmodem 24, 46
          Gputc     19, 24, 43, 47, 49
          Gputs     19, 24, 43, 48, 49
          Hardware Handshaking     64
          InitAnsi  14, 24, 49
          Initializing
            ANSI driver  49
            Interrupt handlers     64
          InitPort  14, 24, 51
          Input
            From com port     17, 24, 28, 29, 60
            From local & remote    17, 26
            From local keyboard    12, 17, 24, 42, 69
          INSTRING  66
          Int14Set  14, 24, 36, 52
          Interrupt handlers
            Communications    8, 14, 57
            Ctrl-Break   8, 58, 63
          IRQ  10, 64
          Iscd 24, 53
          Keyboard  12, 17, 26, 42, 69



                                       Page 75



          GAP Communications                                         CLACOM


            Clarion Key Codes 12, 42
          KEYCODE   12, 42
          Modem     38, 41, 51, 72
            Sending strings to     54
          ModemPuts 24, 54
          ModemStat 24, 55
          Noascmes  23
          Nocts     23
          NULL Modem     64, 72
          Output
            To com port  17, 24, 30, 31, 32
            To local screen   17, 24, 47, 48
            To modem     54
          Overlays  8
          Pausing   67
          Port 9, 14, 34, 35, 36, 38, 39, 41, 51, 64
          PosCursor 24, 56
          Program
            Crashing     8
          Protocols 5, 11, 21, 23, 37, 46, 68
            External     21, 23
          Receive buffer 24, 26, 27, 28, 29, 60, 64
          RESETDIG.EXE   9, 11, 39, 40
          ResetPort 24, 57
          RestCbreak     24, 58
          ROVERLAY.EXP   8
          Rts  24, 59, 64
          Rxempty   24, 60
          Scan codes     42
          Screen    24, 43, 47, 48, 49, 56
            Clearing     47
            Color   49
            Columns 49
            Cursor  33
            Output  17
            Rows    49
          Screen Buffer  20, 43
          SendBreak 24, 61
          SendZmodem     24, 62
          SetCbreak 24, 63
          SETPATH   46
          SetPort   14, 24, 51, 64
          SHOW 49
          SHUTDOWN  58
          Standard Interface  9, 14, 51, 57, 64
          StrHex    24, 40, 65
          Strings   66
            Hexadecimal  40



                                       Page 76



          GAP Communications                                         CLACOM


            INSTRING     66
            Sending to com port    24, 32, 54
            Sending to local screen     24, 48
            Sub string   66
          StrWord   24, 66
          Timer     24, 67
          Transmit Buffer     24, 34
            Free Space   35
          TYPE 22
          UpLoad    24, 68
          Uploading Files     11, 62, 68
          Video Memory   43
          Xmodem    5, 11, 24, 37, 68
          Ymodem    5, 11, 24, 37, 68
          Zmodem    5, 11, 46, 62




































                                       Page 77