
02/14/94

  CLACom is now compatible with Clarion Graphics modes and the
  GUI.

    To demonstrate the GUI capabilities, there is a GUI version
    of the sample application GTERM, called GTERMG.APP.

    Programming wise, you do not need to do anything different
    as far as CLACom is concerned to utilize the Communications
    routines in a GUI application.

    The GTERMG.* files contain the GUI version of the sample
    application.


  The sample applications now demonstrate how to use the Scroll
  Back or Capture buffers. Capturing of data is automatic once
  you tell CLACom to turn on the capture buffer. However, what
  you do with this buffer is up to your application. The data
  is saved to a file (the name of which you specify when initializing
  the capture buffer). You must use Clarion to provide routines for
  Viewing the data in this file.

  There are two functions that interface with the capture routines:

    SetCaptureFile(*CSTRING),PASCAL,RAW,NAME('SETCAPF')

      CSTRING   filename                 Name of Capture File

      This procedure tells the Capture routines what name to
      give to the capture file. It returns nothing.


    SetCapture(SHORT),SHORT,PASCAL,NAME('SETCAPB')

      SHORT     flag                      0 = Turn Buffer Off
                                          1 = Turn Buffer On

    This function turns the Capture buffer On or Off. It returns
    0 for no error or 1 if there is an error allocating memory or
    opening the file.

    You must be sure to call SetCapture with the 'flag' parameter
    set to 1 when you are finished with the capture file. Otherwise
    buffer memory will remain allocated and the buffer contents
    will not be flushed to disk.


  The following is an example of using a capture buffer:

    DATA

    gotcap      BYTE                      ! true if designated a Capture File
    ScrFile     CSTRING(64)               ! Name of ScrollBack File
    CapFile     STRING(64)                ! Name of Capture File

    CODE

    ! set up an automatic Scroll Back Buffer, User doesn't have 
    ! to do anything

    gotcap = 0                            ! if 1, use designated Capture File
    ScrFile = 'GTERM$$.CAP'               ! Give Scroll File a name
    Do TurnOnCapture                      ! Call routine to turn on Capture

    ...                                   ! your program code here

    ! end of procedure, close Scroll Back Buffer

    retchr = SetCapture(0)                ! Turn Capture Off
 
    Return                                ! Return from Clarion Procedure

    TurnOnCapture Routine                 ! Turn on Capture
       SetCaptureFile(ScrFile)            ! Tell the Capture name of file
       if SetCapture(1)                   ! and turn on Capture
          Open(CaptureErr)                ! couldn't allocate memory
          bell()                          ! make noise
          Accept                          ! tell um
          Close(CaptureErr)               ! close error screen
       end
       Exit

  
  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.


  There is a new function that allows you to retrieve the Line
  Status. It is called 'LineStat' and is prototyped as follows:

    LineStat(SHORT),BYTE,PASCAL,NAME('LINESTAT')

    The function is called passing the port number as a parameter. It
    returns a BYTE containing the last Line Status on the port. The
    Line Status contains the following Bit Values (or 0 if there
    was no Line Status interrupt):

        Bit 1 = Overrun Error
        Bit 2 = Parity Error
        Bit 3 = Framing Error


01/27/94

  Fixed a problem with Ymodem Uploads wherein the file that was
  being sent was left open.

  Fixed a problem with ASCII Downloads where if you pressed a
  key while the ASCII receive was in progress, the computer would
  lock up.

  There is a new global variable that is available to your application.
  It is defined as:

         asciidel      SHORT,EXTERNAL,NAME('asciidel')

      where 'asciidel' is the number of clock tics to delay after sending
      each line in a file.

  The delay was previously hard coded as 2 seconds. It is now 0 seconds
  (no delay) so if you need a delay after sending a line of text, you
  will need to set 'asciidel' to the number of clock tics prior to
  calling the Download function (there are 18 tics per second).

  There is an alternate 'SendZmodem' procedure that you may call. It
  is prototyped as follows:

      SendZmodem1(SHORT,*CSTRING,*CSTRING,SHORT),SHORT,RAW,NAME('_send_zmodem1')

  This alternate procedure allows you to control the file sends according
  to your needs. This is especially useful if you need to send more than
  1 file and the files are not all in the same directory.

    SendZmodem1(port,filename,path,flag)

    SHORT   port                          COM Port Number
    CSTRING filename                      Name of File To Send
    CSTRING path                          Path of File To Send
    SHORT   flag                          Control Flag

    Filename is the name of the file you wish to send. This should
    be a NULL (filename = '') when ending the batch.

    Path is 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 only have
    1 file to send, you would call this function twice. If you
    have 3 files to send, you would call this function 4 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 function returns 0 if the send was successful, or a 1 if
    the file could not be opened or there was an error sending the
    file.

    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
             Break
          End
       End

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


11/19/93

  You may now set 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 adding the following to your
  Global Data Section:

          combufsiz     USHORT,EXTERNAL,NAME('combufsiz')

    Prior to calling 'SetPort', set the size of the Receive Buffer
    you desire.

    Example:

       combufsiz = 1024                   ! use 1k buffer

       if SetPort(0,0,0)                  ! Set Up COM 1
          ShowError('Unable To Initialize Port')
       end


  Three new functions have been added and are prototyped as follows:

    RecvCount(SHORT),USHORT,PASCAL,NAME('RCVCOUNT')
    PeekChr(SHORT,BYTE),SHORT,PASCAL,NAME('PEEKCHR')
    ComGets(SHORT,*CSTRING,BYTE),SHORT,PASCAL,RAW,NAME('COMGETS')


    RecvCount returns the number of characters in the Receive Buffer
    waiting to be read.

       port    SHORT
       numchrs USHORT

       port = 0                           ! use COM 1

       numchrs = RecvCount(port)          ! get # of chars in buffer



    PeekChr returns true (1) if a certain character is in the Receive
    Buffer. If the character is not in the buffer, it returns 0.

       port SHORT

       port = 0                           ! use COM 1

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



    ComGets retrieves a string of characters up to, but not including
    a certain character. In stores the characters in the string that
    you pass as a parameter. Characters are stored until the terminator
    is encountered. The terminator is read, but not stored.

    You pass the following parameters to the function:

       port       - COM Port Number
       string     - a CSTRING of sufficient length
       terminator - the character to look for
       
    The return value is either 0 or the number of characters stored in
    the string. If a 0 is returned, it means the terminating character
    was the first character in the Receive Buffer (in this case, the
    passed string will set to a NULL string)

    Warning: 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.


       port     SHORT
       numbytes SHORT
       comstr   CSTRING(255)

       port = 0                               ! use COM 1

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