ftp.wwiv.com

home *** CD-ROM | disk | FTP | other *** search

/ ftp.wwiv.com / ftp.wwiv.com.zip / ftp.wwiv.com / pub / MISC / CLACOM.ZIP / CLACOM.TXT < prev next >

Wrap

Text File | 1995-01-04 | 171KB | 5,929 lines

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