
























                                     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                                  10
               Key Codes                                                 13


          Port Initialization                                            15



          Input & Output                                                 19



          File Transfers                                                 23



          Capture Buffers                                                26



          Sample Application                                             28



          Global Variables                                               31



          Functions - Quick Reference                                    32



                                       Page 3






          Functions - Detailed Reference                                 34



          Appendix A                                                     93



          Appendix B                                                     96



          Index                                                          97






































                                       Page 4



          GAP Communications                                         CLACOM




          Description


          CLACOM is  a professional  communications library for programmers
          using the  Clarion Database Developer. It allows you to integrate
          interrupt driven,  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.  In  addition,  the
          Clarion GUI Kit is supported for Graphics applications.


          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 Hardware Flow Control (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  five 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  one 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 create a file that
          is used  by the  Project System  to determine  how  segments  are
          loaded. In  your Clarion directory is a file called ROVERLAY.EXP.
          Copy this  file to  your application's  directory, renaming it in
          the process  by giving  it the same base name as your application
          and with  an .EXP  extension. Next,  edit the  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 Export 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.

          Be sure  to name  this file  correctly or the Project System will
          not use it. Its base name (the first 8 characters) is the same as
          your application's base name. Its 3 character extension is "EXP".
          For instance,  in the  GTERM sample  application, the name of its
          Export File is GTERM.EXP.

          If your  Overlayed or  Protected Mode  application locks  up  the
          computer, causes an XTRACE, or causes an Exception Error, and you
          can attribute  the problem  to CLACOM,  check your  application's



                                       Page 8



          GAP Communications                                         CLACOM


          directory for  the presence  of the  Export File and make sure it
          contains the correct 2 lines as discussed above.

















































                                       Page 9



          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 PRINTED MANUAL




          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 PRINTED MANUAL



                                       Page 10



          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 PRINTED MANUAL




          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 11



          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.













































                                       Page 12



          GAP Communications                                         CLACOM


          Key Codes

          CLACOM includes  a function  called GetKeyc.  If your application
          needs to  send key  codes 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
          key code  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 extended 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 key codes
          that GetKeyc  returns. Appendix  A shows the actual key typed and



                                       Page 13



          GAP Communications                                         CLACOM


          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-
          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    BYTE
             retchr    SHORT

             retchr = GetKeyc()                   ! Get Key Press

             if retchr = BSKey                    ! Backspace hit
               keychr = retchr                    ! Strip high Byte
               ComPutc(0,keychr)                  ! Actually sends a Ctrl-B
             end


          This will work:

             keychr    BYTE
             retchr    SHORT

             retchr = GetKeyc()                   ! Get Key Press

             if retchr = 8                        ! Backspace hit
               keychr = retchr                    ! Strip high Byte
               ComPutc(0,keychr)                  ! Sends an 8 (backspace)
             end





















                                       Page 14



          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 in that 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 Interfaces are
          0 based.  Your users will not be accustomed to entering 0 for COM
          1 or  1 for  COM 2,  therefore your application 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.














                                       Page 15



          GAP Communications                                         CLACOM




               NOTE: It  is imperative that you call InitAnsi prior to
               using any  CLACOM function,  particularly Gputc, Gputs,
               or any of the File Transfer routines. The need for this
               is particularly  important  if  you  are  generating  a
               Protected Mode  application because  the screen  output
               functions write  directly to  video memory. In order to
               directly address  video memory, these functions need to
               know the  video segment  address. The  default for this
               address is  B800 or  A000.  In  Protected  Mode,  these
               addresses are not valid. One of the reasons for calling
               InitAnsi is  so  that  it  may  determine  the  correct
               segment address  to use when accessing video memory. If
               you forget to call InitAnsi, your program will crash as
               soon as a character is written to the display.


          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 configure the port accordingly:

             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









                                       Page 16



          GAP Communications                                         CLACOM


             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'      ! 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
             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
               




                                       Page 17



          GAP Communications                                         CLACOM


               ! 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 18



          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 Key Code Equate
          labels since they are mapped to different codes:

             comport   SHORT
             retchr    SHORT
             keychr    BYTE

             retchr = GetKeyc()                   ! get a keyboard char

             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 19



          GAP Communications                                         CLACOM


          The following  example is  similar to the above but in this case,
          the remote  end can  handle  extended  keyboard  codes  (commonly
          called DoorWay mode):

             comport   SHORT
             retchr    SHORT
             keychr    BYTE

             retchr = GetKeyc()                   ! get a keyboard char

             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                           ! nothing we care about
                     keychr = retchr              ! Translate to BYTE value
                     ComPutc(comport,0)           ! flag it as 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




                                       Page 20



          GAP Communications                                         CLACOM


          option for each entry in the phone book. Characters received from
          the communications port are never sent back out the port.

          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 char

             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  to  not  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



                                       Page 21



          GAP Communications                                         CLACOM


          are no  characters waiting  to be  read. The return value must be
          assigned to a BYTE before it can be displayed by Gputc.

          An example of ComGetc and Gputc together:

             comport   SHORT
             retchr    SHORT
             keychr    BYTE

             retchr = ComGetc(comport)            ! get a remote char

             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 22



          GAP Communications                                         CLACOM


          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.

          To Download  (receive) files  using the above protocols, you call
          the DownLoad  function. The  equivalent Zmodem function is called
          GetZmodem. To  Upload (send) files using the above protocols, you
          call the  UpLoad function.  The  equivalent  Zmodem  function  is
          called SendZmodem or SendZmodem1.

          When transferring  files you have two options when displaying the
          transfer statistics  (i.e., the  CPS rating,  bytes  transferred,
          progress  meter,  etc.).  You  can  use  the  built  in  Transfer
          Statistics Window or display your own window. The built in window
          may not  be suitable for some applications. For instance, you may
          not like  its colors  or its  screen position.  To use  your  own
          Transfer Statistics  Window, simply  pass the  value of  1 in the
          statfunc parameter when calling the Upload or Download functions.





                                       Page 23



          GAP Communications                                         CLACOM


          When using  your own window, the file transfer statistics will be
          displayed according to how you design the screen. You may display
          some or  all of  the statistics.  Because Clarion does not have a
          pointer data  type,  the  transfer  functions  cannot  call  your
          procedure so  that you  may keep  track of  your own  statistics.
          Instead, all  they can  do is  update your  transfer window. This
          means that your screen structure will need to be designed so that
          it uses  the variables  that the  transfer functions  use to keep
          track of  the statistics.  These variables are all of the CSTRING
          data type  and are  usable by  your Clarion application simply by
          declaring a  GROUP structure  over the first variable. To utilize
          these  variables  in  your  screen  structure,  declare  a  GROUP
          structure as follows:

            TransferVars  GROUP, PRE(XFR), EXTERNAL, NAME('xfervars')
            FileName      CSTRING(128)            ! File Name
            FileSize      CSTRING(14)             ! Size of File
            Blocks        CSTRING(8)              ! # of Blocks in File
            Bytes         CSTRING(10)             ! # of Bytes in File
            Errors        CSTRING(8)              ! Current errors
            CPS           CSTRING(10)             ! Current CPS Rating
            StatusMes     CSTRING(26)             ! Current Status Message
            Protocol      CSTRING(14)             ! Current Protocol
            StatMeter     CSTRING(34)             ! Progress Meter
                          End


























                                       Page 24



          GAP Communications                                         CLACOM


          You will probably have to code the screen structure by hand since
          Clarion does  not allow you to select global variables for use in
          screen fields.  You can  use the  screen structure  in the sample
          application as  a template for your own screens. To reference the
          transfer statistics  variables, you  declare an  ENTRY field with
          the SKIP attribute using one of the above variable names:

            XFERSCREEN  SCREEN(12,60),PRE(XSC),CENTER,SHADOW,COLOR(30)
              ROW(2,4)  STRING('File Name :')
              ..........
              ROW(5,7)  STRING('Blocks :')
              ..........
              ROW(8,7)  STRING('Status :')
              ROW(2,16) ENTRY(@S14),USE(XFR:FileName),SKIP,COLOR(63,78,120)
              ROW(5,16) ENTRY(@S8),USE(XFR:Blocks),SKIP,COLOR(63,78,120)
              ROW(8,16) ENTRY(@S26),USE(XFR:StatusMes),SKIP,COLOR(63,78,120)
            End.

          Prior to  calling an  Upload or Download function you should open
          your transfer  screen. When  the file  transfer is completed, you
          should then  close your screen. The transfer routines will update
          your screen after each block of data is sent or received (this is
          the equivalent to you calling the Clarion Display procedure).

          Note that  when using  your own  transfer window,  if there  is a
          critical error  such as  the inability to open the file, no error
          message will  be displayed. You should check the return code from
          the transfer  functions and  display your  own error  message  if
          necessary.

          When Downloading (receiving) files, the files will be placed into
          the current working directory. If you want the files to be placed
          into a  specific directory, you should change into that directory
          prior to  calling a  Download function.  When Uploading (sending)
          files, the  files are  expected to  be  in  the  current  working
          directory. You  need to  change into whatever directory the files
          are located in. One exception to this is Zmodem where there is an
          alternate Send  function that  allows you  to pass  the directory
          path as  one of  the parameters  (please see  SendZmodem1 in  the
          Reference Section for more information about this function).











                                       Page 25



          GAP Communications                                         CLACOM


          Capture Buffers


          CLACOM supports  automatic Scroll  Back or  Capture Buffers. When
          enabled, any  data (with the exception of ANSI sequences) that is
          sent to  the ANSI  driver using  Gputs or Gputc is also placed in
          the capture buffer.

          The capture  buffer is  capable of  holding 64k  of data  and  is
          automatically written  to disk when it becomes full. After a disk
          write, the  buffer is  reset so  that another  64k of data can be
          stored.

          Two  functions   are  provided  to  support  capturing  of  data.
          SetCaptureFile tells  the capture  routines what name to give the
          capture file.  It should be called first. If you do not call this
          procedure then  a default name will be used for the capture file.
          SetCapture is used to turn the capture buffer on or off. You must
          always be  sure to  call SetCapture with a parameter of 0 to turn
          the capture  buffer off  when you  are finished  with the capture
          file. Failure to do so will leave the buffer memory allocated and
          will prevent  flushing the  capture data  to disk (whatever is in
          the buffer will be lost).

          CLACOM is responsible for capturing and saving the data. What you
          do with the data is up to your application. If you would like for
          your users  to be able to view the data, you will need to provide
          Clarion routines for doing so. If you do provide a View procedure
          to allow  your users  to view  the capture data, be sure to first
          call SetCapture with a parameter of 0 to flush the capture buffer
          to disk.  When you  regain control  from the  View procedure, you
          will once  again need  to call  SetCapture with  a parameter 1 to
          turn the capture buffer back on.


















                                       Page 26



          GAP Communications                                         CLACOM


          The following is an example of using a capture buffer:

             ScrFile  CSTRING(64)                 ! Name of ScrollBack File

             ! set up an automatic Scroll Back Buffer

             ScrFile = 'GTERM$$.CAP'              ! Give Scroll File a name

             Do TurnOnCapture                     ! Turn on Capture

             .....                                ! your program code here


             ! end of procedure, close Scroll Back Buffer

             retchr = SetCapture(0)               ! Turn Capture Off

             Return                               ! Return from Procedure

             TurnOnCapture Routine                ! Turn on Capture
               SetCaptureFile(ScrFile)            ! Tell Capture File Name
               if SetCapture(1)                   ! and turn on Capture
                 Open(CaptureErr)                 ! couldn't allocate Mem
                 bell()                           ! make noise
                 Accept                           ! tell um
                 Close(CaptureErr)                ! close error screen
               end
               Exit                               ! Return from Routine


          GTERM gives  an excellent  example of how to utilize an automatic
          Scroll Back  buffer and  allow the  user  to  specify  a  Capture
          Buffer. It  also shows how to allow the user to view the contents
          of the  Scroll Back  or the Capture Buffer, clear the buffer, and
          save it under a different name.
















                                       Page 27



          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.  GTERMG  is  a  GUI
          version of the same program (it requires the Clarion GUI kit).

          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



                                       Page 28



          GAP Communications                                         CLACOM


          the same  manner as  Dial,  with  one  exception.  For  the  Port
          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 Key Codes 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 29



          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!

































                                       Page 30



          GAP Communications                                         CLACOM


          Global Variables


          The following  variables are  declared global  and may be used by
          your application  to alter  the behavior  of  the  Communications
          routines. The  names shown  are the  actual  names  used  by  the
          Communications routines.  See the  sample application  to see how
          they are declared and named:

            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.
            combufsiz Sets the  size of  the Receive  Buffer when using the
                      Direct Interface. The Receive Buffer defaults to 6144
                      bytes. This  has proven  to be  the optimal  size for
                      high speed  communications when using a file transfer
                      protocol such  as Ymodem-G.  However you may increase
                      or decrease  this  size  by  changing  this  variable
                      (decreasing the  size will  typically result  in lost
                      data at high speeds).
            crscur    Contains the  ANSI driver's  current Cursor Position.
                      The high  byte contains  the row  coordinates and the
                      low byte  contains the  column coordinates.  Changing
                      this variable changes the cursor position.
            gnormal   Contains the ANSI driver's current Color. This is the
                      initial color  that you  pass to InitAnsi but it will
                      change whenever  an ANSI  color sequence  is sent  to
                      Gputs or  Gputc. Changing  this variable  changes the
                      color of  subsequent  characters  sent  to  the  ANSI
                      driver.
            meterchr  This variable defines the character that makes up the
                      Progress Meter on the File Transfer Status Window.
            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.
            usefifo   If a  Communications Port has a 16550 UART installed,
                      the FIFO  buffers on  the UART  will automatically be
                      turned  on   and  utilized.   Some  UART  chips  have
                      defective FIFO  implementations where  turning on the
                      FIFO  buffers   will  cause  incorrect  behavior.  To
                      disable the FIFO buffers, set this flag to 0.





                                       Page 31



          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.
          ComGets        - Gets a string of characters up to deliminator.
          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.
          GetCRC16       - Returns a 16 bit CRC value.
          GetCRC32       - Returns a 32 bit CRC value.
          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 (Int14/EBIOS Interface).
          Iscd           - Checks if there is a Carrier.
          LineStat       - Get UART Line Status.
          ModemPuts      - Send a string to the modem.
          ModemStat      - Get Modem Status.
          PeekChr        - Check if character is in Receive Buffer.
          PosCursor      - Update ANSI Driver Cursor Position.
          RecvCount      - Returns # of characters in Receive Buffer.
          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.
          SendZmodem1    - Send files using Zmodem (alternate function).
          SetCapture     - Turns Capture Buffer On or Off.
          SetCaptureFile - Sets the name of Capture File.
          SetPort        - Initializes Communications port.
          SetCbreak      - Initializes Ctrl-Break vector.



                                       Page 32



          GAP Communications                                         CLACOM


          StrHex         - Translate Hex String to number.
          StrWord        - Find substring in string.
          Timer          - Time Delay.
          UpLoad         - Send files using Xmodem and Ymodem.















































                                       Page 33



          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 34



          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 35



          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 recv buf (COM 1)


































                                       Page 36



          GAP Communications                                         CLACOM


          ComGetb
          -----------------------------------------------------------------

          Purpose       Retrieves all the characters in the Receive Buffer.

                        ComGetb(port, str)

                        SHORT port        COM Port Number
                        CSTRING str       String to store characters in

          Type          Function - Returns SHORT

          Description   Retrieves all  of the  characters  in  the  Receive
                        Buffer and stores them in the passed string.

                        If a 0 is returned, it means the Reveive Buffer was
                        empty.  In   this  case,  a  NULL  string  will  be
                        returned.

                        The string  passed to  this  function  must  be  of
                        sufficient length to hold all of the characters. It
                        is very  easy to  overwrite code  or data with this
                        function if  the passed  string  parameter  is  not
                        large enough to hold all of the data.

          Return Value  0 or  the number of characters stored in the passed
                        string.

          Example

             port      SHORT
             numbytes  SHORT
             cstr      CSTRING(255)

             port = 0                             ! use COM 1

             numbytes = ComGetb(port,cstr)        ! get the string














                                       Page 37



          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 character

             keychr    BYTE
             retchr    SHORT
             comport   SHORT

             comport = 0                          ! use COM 1

             retchr = ComGetc(comport)            ! get a character

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












                                       Page 38



          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 39



          GAP Communications                                         CLACOM


          ComGets
          -----------------------------------------------------------------

          Purpose       Gets a string of characters up to terminator.

                        ComGets(port, str, chr)

                        SHORT port      COM Port Number
                        CSTRING str     String to store characters in
                        BYTE chr        Character to look for

          Type          Function - Returns SHORT

          Description   Retrieves a  string of  characters up  to, but  not
                        including,   the    terminating   character.    The
                        characters are  stored in  the string that you pass
                        as a  parameter. Characters  are stored  until  the
                        terminator is encountered.

                        If a 0 is returned, it means the terminator was the
                        first character  in the  Receive  Buffer.  In  this
                        case, a NULL string will be returned.

                        This function does not time out. It will not return
                        until it encounters the terminator. Unless you know
                        for a fact that the terminating character is in the
                        Receive Buffer,  you should  call PeekChr  first to
                        make certain  that the  terminating character is in
                        the buffer.

                        The string  passed to  this  function  must  be  of
                        sufficient length  to hold  all of  the  characters
                        that are  stored while  looking for the terminator.
                        It is very easy to overwrite code or data with this
                        function if  the passed  string  parameter  is  not
                        large enough to hold all of the data.

          Return Value  0 or  the number of characters stored in the passed
                        string.












                                       Page 40



          GAP Communications                                         CLACOM


          Example

             port      SHORT
             numbytes  SHORT
             cstr      CSTRING(255)

             port = 0                             ! use COM 1

             if PeekChr(port,10)                  ! check for Line Feed
               numbytes = ComGets(port,cstr,10)   ! get the string
             end








































                                       Page 41



          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 to send
                        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 42



          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                  ! strip high byte
                 ComPutc(comport,keychr)          ! and send it to remote
               end
             end

















                                       Page 43



          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 44



          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 45



          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 46



          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 47



          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  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 48



          GAP Communications                                         CLACOM


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

          Purpose       Receives one or more files.

                        DownLoad(port, protocol, filename, statfunc)

                        SHORT port           COM Port Number
                        SHORT protocol       Number of protocol to use
                        CSTRING filename     Name of file to download
                        SHORT statfunc       0 or 1 (see below)

          Type          Function - Returns SHORT

          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.

                        The statfunc  parameter allows  you to override the
                        default Transfer  Status Window. A value of 0 means
                        the internal  window will be displayed and updated.
                        A value  of 1  means you  will open your own window
                        and the transfer statistics will be displayed on it
                        instead.

          Return Value  0 for  successful transfer. If an error occurs, the
                        following values are returned:

                        1 - Error opening file    6 - Error writing file
                        2 - Receiver cancelled    7 - CRC error
                                                      (1K Xmodem-G
                        3 - Sender cancelled          or Ymodem-G)
                        4 - Time out              8 - Too many errors
                        5 - No carrier            9 - Block error





                                       Page 49



          GAP Communications                                         CLACOM


          Example

             cstr  CSTRING(100)

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

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










































                                       Page 50



          GAP Communications                                         CLACOM


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

          Purpose       Reset Modem attached to a DigiBoard Port.

                        Drestore(port)

                        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 51



          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 52



          GAP Communications                                         CLACOM


                        The channel  is the  Communications Port  to use on
                           _
                        the DigiBoard.  When using  the  Direct  Interface,
                        Channel  Numbers   are  0  based.  Therefore,  this
                        parameter 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,0,38400,0,8,1)
               ShowError('Unable To Initialize DigiBoard')
             end














                                       Page 53



          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)                             ! wake up modem
             ComPuts(0,cstr)                 ! reset the modem






















                                       Page 54



          GAP Communications                                         CLACOM


          GetCRC16
          -----------------------------------------------------------------

          Purpose       Returns a 16 bit CRC.

                        GetCRC16(crc, value)

                        SHORT crc       Current CRC
                        SHORT value     Vaule to add to CRC

          Type          Function - Returns SHORT

          Description   This is  an internal  function  used  by  the  File
                        Transfer routines  to calculate the 16 bit CRC of a
                        data block.  To use,  you first set the initial CRC
                        value to  0. Then  for each  character (typically a
                        data buffer) you pass the current CRC value and the
                        character for which you wish to obtain a CRC from.

          Return Value  16 Bit CRC value.

          Example

             crc16   SHORT
             value   SHORT

             crc16 = 0                            ! Initialize

             crc16 = GetCRC16(crc16,value)        ! get CRC






















                                       Page 55



          GAP Communications                                         CLACOM


          GetCRC32
          -----------------------------------------------------------------

          Purpose       Returns a 32 bit CRC.

                        GetCRC32(value,crc)

                        SHORT value     Vaule to add to CRC
                        LONG crc        Current CRC

          Type          Function - Returns LONG

          Description   This is  an internal  function used  by the  Zmodem
                        Transfer routines  to calculate the 32 bit CRC of a
                        data block.  To use,  you first set the initial CRC
                        value  to   0FFFFFFFF.  Then   for  each  character
                        (typically a  data buffer) you pass the current CRC
                        value and  the character  for  which  you  wish  to
                        obtain a CRC from.

          Return Value  32 Bit CRC value.

          Example

             crc32   LONG
             value   SHORT

             crc32 = 0FFFFFFFFh                   ! Initialize

             crc32 = GetCRC32(value,crc32)        ! get CRC





















                                       Page 56



          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  code  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 57



          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 58



          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.

             GetScrn()                            ! update Screen Buffer

             ! 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,no upload
                   Open(NotOnLine)                ! Tell um can't upload
                   bell()                         ! Make noise
                   Beep(0,300)                    ! Wait 3 seconds
                   Close(NotOnLine)               ! Close Screen
                 else                             ! otherwise, upload away
                   UpFile
                 end
             end






                                       Page 59



          GAP Communications                                         CLACOM


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

          Purpose       Receives 1 or more files using the Zmodem Protocol.

                        GetZmodem(port, statfunc)

                        SHORT port      COM Port Number
                        SHORT statfunc  0 or 1 (see below)

          Type          Function - Returns SHORT

          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.

                        The statfunc  parameter allows  you to override the
                        default Transfer  Status Window. A value of 0 means
                        the internal  window will be displayed and updated.
                        A value  of 1  means you  will open your own window
                        and the transfer statistics will be displayed on it
                        instead.

          Return Value  0 for  successful transfer. If an error occurs, the
                        following values are returned:

                        1 - Error opening file    4 - Time out
                        2 - Receiver cancelled    5 - No carrier
                        3 - Sender cancelled      6 - Error writing file

          Example       error = GetZmodem(0,0)    ! Receive using Zmodem


















                                       Page 60



          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 61



          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 COM 1

             ! 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 62



          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) 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




                                       Page 63



          GAP Communications                                         CLACOM


                        sequences 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 64



          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.

                        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 COM 1
              ShowError('Unable To Initialize Port')   ! N,8,1 - 38,400 bps
            end



















                                       Page 65



          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 66



          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 67



          GAP Communications                                         CLACOM


          IsRing
          -----------------------------------------------------------------

          Purpose       Check to see if the Phone is Ringing.

                        IsRing(port)

                        SHORT port      COM Port Number

          Type          Function - Returns SHORT

          Description   This function  allows you check to see if the Phone
                        is Ringing.

          Return Value  Returns 0 if the phone is not ringing, 1 if it is.

          Example

             port  SHORT
             cstr  CSTRING

             port = 0                             ! Use COM 1
             cstr = 'ATA'                         ! Answer Phone string

             if IsRing(0)                         ! is there a carrier?
               ComPuts(port,cstr)                 ! Tell Modem to Answer
             end
























                                       Page 68



          GAP Communications                                         CLACOM


          LineStat
          -----------------------------------------------------------------

          Purpose       Returns UART Line Status.

                        LineStat(port)

                        SHORT port      COM Port Number

          Type          Function - Returns BYTE

          Description   Returns the value of the Line Status Register. Note
                        that the value returned is the contents of the Line
                        Status Register  at the  time the  last Line Status
                        Interrupt occured.  This information  will tell you
                        if there was a Receiver Overrun, Parity, or Framing
                        error. The  value is  a Bit Flag. The bits have the
                        following meanings:

                        1 - Overrun Error
                        2 - Parity Error
                        3 - Framing Error

                        If a  bit is on, it is set to a 1. If it is off, it
                        is set  to a  0. To test if a bit is on you use the
                        Clarion BAND function.

          Return Value  Bit Flag containing Line Status.

          Example

             linstat BYTE

             linstat = LineStat(0)                ! get Line Status

             if BAND(linstat,02h)                 ! check for Overrun
               ! Lost some incomming data
             end













                                       Page 69



          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(0,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 70



          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. The
                        value is  a Bit  Flag. The  bits have the following
                        meanings:

                        4 - CTS    (Clear To Send)
                        5 - DSR    (Data Set Ready)
                        6 - RI     (Ring Indicator)
                        7 - RLSD   (Carrier Detect)

                        If a  bit is on, it is set to a 1. If it is off, it
                        is set  to a  0. To test if a bit is on you use the
                        Clarion BAND function.

          Return Value  Bit Flag containing Modem Status.

          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 71



          GAP Communications                                         CLACOM


          PeekChr
          -----------------------------------------------------------------

          Purpose       Checks if character is in Receive Buffer.

                        PeekChr(port, chr)

                        SHORT port      COM Port Number
                        BYTE chr        Character to check for

          Type          Function - Returns SHORT

          Description   This function  checks the Receiver Buffer to see if
                        it contains a certain character.

          Return Value  0 if character not in buffer, 1 if it is.

          Example

             port    SHORT

             port = 0                             ! use COM 1

             if PeekChr(port,10)                  ! check for Line Feed
               ! there is a Line Feed in the Buffer
             end

























                                       Page 72



          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






























                                       Page 73



          GAP Communications                                         CLACOM


          RecvCount
          -----------------------------------------------------------------

          Purpose       Gets number of characters in Receive Buffer.

                        RecvCount(port)

                        SHORT port      COM Port Number

          Type          Function - Returns USHORT

          Description   This function  returns the  number of characters in
                        the Receive Buffer waiting to be read.

          Return Value  Number of characters in Receive Buffer.

          Example

             port    SHORT
             numchrs USHORT

             port = 0                             ! use COM 1

             numchrs = RecvCount(port)            ! get # of chars



























                                       Page 74



          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 75



          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






























                                       Page 76



          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 77



          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 for something




























                                       Page 78



          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 79



          GAP Communications                                         CLACOM


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

          Purpose       Sends one or more files using Zmodem.

                        SendZmodem(port, filename, statfunc)

                        SHORT port        COM Port Number
                        CSTRING filename  Name of file to upload
                        SHORT statfunc    0 or 1 (see below)

          Type          Function - Returns SHORT

          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.

                        The statfunc  parameter allows  you to override the
                        default Transfer  Status Window. A value of 0 means
                        the internal  window will be displayed and updated.
                        A value  of 1  means you  will open your own window
                        and the transfer statistics will be displayed on it
                        instead.

          Return Value  0 for  successful transfer. If an error occurs, the
                        following values are returned:

                        1 - Error opening file    4 - Time out
                        2 - Receiver cancelled    5 - No carrier
                        3 - Sender cancelled


          Example

             cstr  CSTRING(100)

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

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







                                       Page 80



          GAP Communications                                         CLACOM


          SendZmodem1
          -----------------------------------------------------------------

          Purpose       Sends one or more files using Zmodem.

                        SendZmodem1(port, filename, path, flag, statfunc)

                        SHORT port        COM Port Number
                        CSTRING filename  Name of file to upload
                        CSTRING path      Path of file to upload
                        SHORT flag        Control Flag
                        SHORT statfunc    0 or 1 (see below)

          Type          Function - Returns SHORT

          Description   This is  an alternate  Zmodem  send  function  that
                        allows you  to control  the file sends according to
                        your needs.  This is  especially useful if you need
                        to send  more than  one file  and the files are not
                        all in the same directory.

                        Filename is  a CSTRING  containing the  name of the
                        file  to   upload.  It  may  not  be  a  Wild  Card
                        Specification.

                        Path is a CSTRING containing the full path to where
                        the file  is located.  It should  be in the form of
                        "C:\FILES", without a trailing slash.

                        Flag is defined as follows:

                        0   =  This is the First File in the Batch.
                       >0   =  This is the Second and Subsequent File.
                       -1   =  End the Batch (no more files to send).

                        You must  always end  the batch with Zmodem. If you
                        have only  one file  to send,  you would  call this
                        function twice.  If you  have three  files to send,
                        you would call this function four times.

                        Generally you call this function from within a loop
                        where the  control variable  is passed  as the flag
                        parameter. After  all files are sent, you then call
                        SendZmodem1 with a flag value of -1.

                        The statfunc  parameter allows  you to override the
                        default Transfer  Status Window. A value of 0 means
                        the internal  window will be displayed and updated.



                                       Page 81



          GAP Communications                                         CLACOM


                        A value  of 1  means you  will open your own window
                        and the transfer statistics will be displayed on it
                        instead.

          Return Value  0 for  successful transfer. If an error occurs, the
                        following values are returned:

                        1 - Error opening file    4 - Time out
                        2 - Receiver cancelled    5 - No carrier
                        3 - Sender cancelled
          Example

             r     SHORT 
             fname CSTRING(100)
             fpath CSTRING(160)

             Loop r = 0 To 3                      ! 4 files to send
               fname = Clip(files[r+1])           ! get file name
               fpath = Clip(filepath[r+1])        ! get file's path

               If SendZmodem1(port,fname,fpath,r,0) NOT= 0
                 Break
               End
             End

             r = SendZmodem1(port,fname,fpath,-1,0)    ! end the Batch

























                                       Page 82



          GAP Communications                                         CLACOM


          SetCapture
          -----------------------------------------------------------------

          Purpose       Turns Capture Buffer On or Off.

                        SetCapture(how)

                        SHORT how       0 = Turn Capture Buffer off
                                        1 = Turn Capture Buffer on

          Type          Function - Returns SHORT

          Description   Turns automatic  data capturing on or off. When the
                        capture buffer  is on,  any data sent to the screen
                        using Gputc  or Gputs  will also  be stored  in the
                        capture buffer (ANSI sequences are stripped).

                        The capture  buffer is  capable of  holding 64k  of
                        data.  When   the  buffer   becomes  full,   it  is
                        automatically written to a disk file.

                        Whenever you  need to  view the capture buffer, you
                        should first  flush the  buffer to  disk by calling
                        SetCapture with  a parameter  of 0. Be sure to turn
                        the buffer  back on  when you  are ready to capture
                        more data.

          Return Value  0  if   memory  for  the  buffer  was  successfully
                        allocated, 1 if there is insufficient memory.






















                                       Page 83



          GAP Communications                                         CLACOM


          Example

             ScrFile CSTRING(64)                  ! Name of ScrollBack File

             ! set up an automatic Scroll Back Buffer

             ScrFile = 'GTERM$$.CAP'              ! Give Scroll File a name

             Do TurnOnCapture                     ! Turn on Capture

             .....     ! your program code here

             ! end of procedure, close Scroll Back Buffer

             retchr = SetCapture(0)               ! Turn Capture Off

             Return    ! Return from Procedure


             TurnOnCapture Routine                ! Turn on Capture
               SetCaptureFile(ScrFile)            ! Name of file
               if SetCapture(1)                   ! and turn on Capture
                 Open(CaptureErr)                 ! No Memory
                 bell()  ! make noise
                 Accept  ! tell um
                 Close(CaptureErr)                ! close error screen
               end
               Exit                               ! Return from Routine























                                       Page 84



          GAP Communications                                         CLACOM


          SetCaptureFile
          -----------------------------------------------------------------

          Purpose       Names the Capture Buffer File.

                        SetCaptureFile(filename)

                        CSTRING filename  Name to use for Capture File

          Type          Procedure

          Description   Names the  file that will be used to store captured
                        data.

          Return Value  None.

          Example       See the example for SetCapture.


































                                       Page 85



          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 86



          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  (unless the nocts flag is set
                        to 1).  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 87



          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 88



          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 89



          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 90



          GAP Communications                                         CLACOM


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

          Purpose       Sends one or more files.

                        UpLoad(port, protocol, filename, statfunc)

                        SHORT port      COM Port Number
                        SHORT protocol  Number of protocol to use
                                                 _
                        CSTRING filename  Name of file to upload
                        SHORT statfunc  0 or 1 (see below)

          Type          Function - Returns SHORT

          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.

                        The statfunc  parameter allows  you to override the
                        default Transfer  Status Window. A value of 0 means
                        the internal  window will be displayed and updated.
                        A value  of 1  means you  will open your own window
                        and the transfer statistics will be displayed on it
                        instead.

          Return Value  0 for  successful transfer. If an error occurs, the
                        following values are returned:

                        1 - Error opening file    4 - Time out
                        2 - Receiver cancelled    5 - No carrier
                        3 - Sender cancelled      6 - Error reading file











                                       Page 91



          GAP Communications                                         CLACOM


          Example

             cstr  CSTRING(100)

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

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










































                                       Page 92



          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 93



          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 94



          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 95



          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 96



          GAP Communications                                         CLACOM




          Index


          Ansi driver    5, 21, 22, 29, 32, 59, 61, 62, 73
            Initializing 15, 32, 63
          ASCII File Transfers     31
          Asciidel  31
          ASK  57
          Base Address   11, 87
          Baud Rate 5, 48, 52, 65, 66, 87
          Capture   26, 83
          Channel   11, 12, 52, 53, 66
          Characters
            In Receive Buffer 72, 74
            Sending to com port    19, 32, 43
            Sending to local screen     19, 32, 61
          Characters Per Second
            Uploading & Downloading     23
          CkeyPress 32, 35
          Clarion
            ASK     57
            Color   63
            CSTRING 34, 44, 49, 53, 54, 62, 70, 80, 88, 89, 91
            Cursor  73
            Export File  8
            INSTRING     89
            KEYCODE 13, 57
            Overlays     8
            Protected Mode    8, 16
            Screen  73
            Screen Buffer     22, 58
            SHOW    63
            Strings 89
            TYPE    29
            Type Checking     34
          ClrBuf    32, 36
          Color     31, 63
          Combufsiz 31
          ComGetb   37
          ComGetc   21, 32, 38
          ComGetd   32, 39
          ComGets   32, 40
          Communications
            Base address 15, 87
            Baud rates   5, 15, 87
            Buffer  31



                                       Page 97



          GAP Communications                                         CLACOM


            Carrier 67
            CTS     31, 87
            DigiBoard    10, 15, 65, 75
            FIFO buffer  5, 15
              Disabling  31
            Initializing 15, 48, 52, 65, 66, 87
            Input   37, 38, 39, 40, 78
            Interface    10, 65, 75
            Interrupt    8, 15, 75
            IRQ     87
            nocts flag   87
            Output  42, 43, 44, 70
            Port    10, 15, 87
          ComPutb   32, 42
          ComPutc   22, 32, 43
          ComPuts   22, 32, 44
          CPS
            Uploading & Downloading     23
          Crash     8, 16, 75
          CRC  55, 56
          Crscur    31
          CSTRING   34, 44, 49, 53, 54, 62, 70, 80, 88, 89, 91
          Ctrl-Break handler  8, 76, 86
          CTS  31, 87
          Cursor    32, 45, 73
            Setting position of    31
          CursorOff 32, 45
          CursorOn  32, 45
          DclrTx    32, 46
          Delaying  90
          DgtTxfree 32, 47
          DigiBoard 10, 65, 75
            Channel 11, 12, 52, 53, 66
            Initializing Port 15, 48, 52, 66
            Resetting Modem   51
            Transmit Buffer   46
              Free Space 47
          Distribution files  6
          Dmodem    32, 48
          DownLoad  32, 49
          Downloading Files   23, 31, 49, 60
            Errors  49, 60
          Drestore  32, 51
          DsetUp    15, 32, 52
          Dtr  32, 54
          Errors
            Download     49, 60
            Exception    8



                                       Page 98



          GAP Communications                                         CLACOM


            Overrun, Parity   69
            Upload  80, 82
          Exception Error     8
          Export File    8
          FIFO buffer    5, 15
            Disabling    31
          File Transfer Statistics 23, 31
          Files
            Capture 26, 83
            Downloading  23, 31, 49, 60
            Uploading    23, 31, 80, 91
          Functions
            CkeyPress    35
            ClrBuf  36
            ComGetb 37
            ComGetc 21, 38
            ComGetd 39
            ComGets 40
            ComPutb 42
            ComPutc 22, 43
            ComPuts 22, 44
            CursorOff    45
            CursorOn     45
            DclrTx  46
            DgtTxfree    47
            Dmodem  48
            DownLoad     49
            Drestore     51
            DsetUp  15, 52
            Dtr     54
            GetCRC16     55
            GetCRC32     56
            GetKeyc 13, 57, 93
            GetScrn 58
            GetZmodem    60
            Gputc   21, 58, 61, 63
            Gputs   21, 58, 62, 63
            InitAnsi     15, 63
            InitPort     15, 65
            INSTRING     89
            Int14Set     15, 66
            Iscd    67
            IsRing  68
            LineStat     69
            ModemPuts    70
            ModemStat    71
            PeekChr 72
            PosCursor    73



                                       Page 99



          GAP Communications                                         CLACOM


            RecvCount    74
            ResetPort    75
            RestCbreak   76
            Rts     77
            Rxempty 78
            SendBreak    79
            SendZmodem   80
            SendZmodem1  81
            SetCapture   26, 83
            SetCaptureFile    26, 85
            SetCbreak    86
            SETPATH 60
            SetPort 15, 87
            SHOW    63
            SHUTDOWN     76
            StrHex  53, 88
            StrWord 89
            Timer   90
            UpLoad  91
          GetCRC16  32, 55
          GetCRC32  32, 56
          GetKeyc   13, 32, 57, 93
          GetScrn   32, 58
          GetZmodem 32, 60
          Global Variables    31
            asciidel     31
            combufsiz    31
            crscur  31
            gnormal 31
            meterchr     31
            noascmes     31
            nocts   31
            usefifo 31
          Gnormal   31
          Gputc     21, 32, 58, 61, 63
          Gputs     21, 32, 58, 62, 63
          Hardware Handshaking     31, 87
          InitAnsi  15, 32, 63
          Initializing
            ANSI driver  63
            Interrupt handlers     87
          InitPort  15, 32, 65
          Input
            From com port     19, 32, 37, 38, 39, 40, 78
            From local & remote    19, 35
            From local keyboard    13, 19, 32, 57, 93
          INSTRING  89
          Int14Set  15, 32, 66



                                      Page 100



          GAP Communications                                         CLACOM


          Interrupt handlers
            Communications    8, 15, 75
            Ctrl-Break   8, 76, 86
          IRQ  11, 87
          Iscd 32, 67
          IsRing    68
          Keyboard  13, 19, 35, 57, 93
            Clarion Key Codes 13, 57
          KEYCODE   13, 57
          Line Status Register     69
          LineStat  32, 69
          Lockup    8, 16, 75
          Meterchr  31
          Modem     51, 54, 65, 96
            Clearing buffer   79
            Sending strings to     70
          ModemPuts 32, 70
          ModemStat 32, 71
          Noascmes  31
          Nocts     31
          Nocts flag     87
          NULL Modem     87, 96
          Output
            To com port  19, 32, 42, 43, 44
            To local screen   19, 32, 61, 62
            To modem     70
          Overlays  8, 16
          Parity Error   69
          Pausing   90
          PeekChr   32, 72
          Phone
            Ringing 68
          Port 10, 15, 48, 65, 87
          PosCursor 32, 73
          Program
            Crashing     8, 16
          Progress Meter 31
          Protected Mode 8, 16
          Protocols 5, 23, 28, 30, 49, 60, 91
            External     28, 30
          Receive buffer 32, 35, 36, 38, 39, 78, 87
            Checking for a Character    72
            Number of characters in     74
            Setting size of   31
          Receiver Overrun    69
          RecvCount 32, 74
          RESETDIG.EXE   10, 12, 52, 53
          ResetPort 32, 75



                                      Page 101



          GAP Communications                                         CLACOM


          RestCbreak     32, 76
          Ring 68
          Rts  32, 77, 87
          Rxempty   32, 78
          Scan codes     57
          Screen    32, 58, 61, 62, 63, 73
            Clearing     61
            Color   63
            Columns 63
            Cursor  31, 45
            Output  19
            Rows    63
          Screen Buffer  22, 58
          Scroll Back Buffer  26, 83
          SendBreak 32, 79
          SendZmodem     32, 80
          SendZmodem1    32, 81
          SetCapture     26, 32, 83
          SetCaptureFile 26, 32, 85
          SetCbreak 32, 86
          SETPATH   60
          SetPort   15, 32, 87
          SHOW 63
          SHUTDOWN  76
          Standard Interface  10, 15, 65, 75, 87
          Statistics
            File Transfer     23, 31
          StrHex    33, 53, 88
          Strings   89
            Hexadecimal  53
            INSTRING     89
            Receiving    37, 40
            Sending to com port    32, 44, 70
            Sending to local screen     32, 62
            Sub string   89
          StrWord   33, 89
          Timer     33, 90
          Transfer Window     23
          Transmit Buffer     32, 46
            Free Space   47
          TYPE 29
          UpLoad    33, 91
          Uploading Files     23, 31, 80, 91
            Errors  80, 82
          Usefifo   31
          Variables
            Global  31
          Video Memory   16, 58



                                      Page 102



          GAP Communications                                         CLACOM


          Xmodem    5, 23, 32, 33, 49, 50, 91
          XTRACE    8, 16
          Ymodem    5, 23, 32, 33, 49, 50, 91
          Zmodem    5, 23, 60, 80















































                                      Page 103
