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