Power-Programmierung

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

/ Power-Programmierung / CD1.mdf / clarion / library / clacom / clacom.txt < prev next >

Wrap

Text File | 1994-02-24 | 129KB | 4,420 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 9 File Transfers 11 KeyCodes 12 Port Initialization 14 Input & Output 17 Sample Application 21 Global Variables 23 Functions - Quick Reference 24 Functions - Detailed Reference 25 Appendix A 69 Page 3 Appendix B 72 Index 73 Page 4 GAP Communications CLACOM Description CLACOM is a professional communications library for programmers using the Clarion Database Developer. It allows you to easily integrate asynchronous communications into your Clarion programs. CLACOM includes robust Communications routines which are fully interrupt driven. Written in highly optimized assembler, they are capable of operating at any speed which the UART on an IBM type of computer is capable of producing. The FIFO buffers in the 16550 UART are fully supported. Hardware flow control (CTS/RTS checking) is automatic. ANSI Terminal Emulation is fully integrated into CLACOM, as are the most popular file transfer protocols. Major Features Supports the FIFO buffers of the 16550 UART chip. Speeds up to 115,200 baud. Supports COM 1 through COM 4 as well as Intelligent DigiBoards using a Direct Programming Interface or a DigiBoard Device Driver. Up to 4 ports can be opened simultaneously (16 ports when using a DigiBoard). Supports CTS/RTS, automatically. Fully self contained, built in ANSI driver for IBM ANSI Terminal Emulation. File transfer protocols include - ASCII, Xmodem, Xmodem- CRC, 1K Xmodem, 1K Xmodem-G, Ymodem, Ymodem-G, and Zmodem. Works with programs compiled as Static, Overlay, Overlay with DLL, Protected, and Protected with DLL. Extremely easy interfacing with Clarion programs. Page 5 GAP Communications CLACOM Getting Started First a note about this documentation. This Text Based manual is identical in content to the Printed Manual except that it lacks formatting and graphics. Some screens can not be reproduced in a document such as this. Font sizes can not be changed when necessary since there is no way of knowing what kind of printer this document will be printed with. The Printed Manual is designed in such a way that it is easy to read and it is easy to find the information you may be looking for. We are unable to do the same with this text based manual. If the documentation references a screen, you will need to run the Example program to see the screen, since we are unable to reproduce it in this Text Based manual. The following files are part of the CLACOM distribution set: CLACOM.TXT - Text Based documentation. Not part of Registered version since its not needed. DXVCLOM.LIB - Library routines for Statically linked Clarion APP. DOVCLCOM.LIB - Library routines for Overlayed Clarion APP. DDVCLCOM.LIB - Library routines for Overlayed Clarion APP using Run Time Librares. DESCLCOM.LIB - Library routines for Protected mode Clarion APP using Run Time Libraries. (1) DEVCLCOM.LIB - Library routines for Statically linked Protected mode Clarion APP. (1) CLACOM.OBJ - Stub for including Module Definitions. CLACOM.INC - Module Structure Include file. GTERM.ZIP - Terminal Emulation example with Clarion source. RESETDIG.ZIP - Program used to reset a DigiBoard COM/Xi. The .OBJ, .LIB and .INC files should be placed in the same directory where the program you intend to use them with resides. GTERM.ZIP contains a Terminal Emulation Clarion Application. It should be placed in its own directory along with the above .OBJ, .LIB and .INC files. (1) Protected Mode Libraries are not included with Shareware version of CLACom. Page 6 GAP Communications CLACOM Integrating with Clarion To tell your Clarion Application that you are using the CLACOM library, follow these steps: Load or Create your application. From the View Menu, select Module View. Select Insert from the Edit Menu. The Module Properties screen will appear. For the Module Name, type CLACOM.OBJ. Select the External Object Module radio button. For the Module Structure Include File, type CLACOM.INC. Select OK. CLACOM.OBJ is a dummy module. It contains no code or data. Its sole purpose is to include the CLACOM procedure definitions. You must now edit the Project File and include the five CLACOM libraries. The fivee libraries are identical with the exception that they were compiled using one of the five Clarion memory models: Static, Overlayed, Overlayed/Runtime, Protected, and Protected/Runtime. Select the Project Menu. Select Change Project File. Select the Module button and then the Insert button. For the Module Name, type: %CLAPFX%CLCOM.LIB Select the External OBJ/LIB Radio button. Finally, save the Project File changes. Your Clarion application is now fully aware of the CLACOM library routines and you will be free to use any of the five standard Memory Models without having to worry about which CLACOM library to use. Page 7 GAP Communications CLACOM Overlays - Protected Mode You must perform one final step before generating your CLACOM application. The Standard Communications interface takes over the interrupt vector for the selected COM Port. This means that the interrupt service routine can not be swapped out. It must remain in memory at all times. The same is true if you enable the Ctrl-Break intercept routine (which you should). In order to keep the Communications routines in memory and prevent them from being swapped out, you must make a change to one of Clarion's files. In the Clarion directory there is a file called ROVERLAY.EXP. Edit this file and add the following lines to the end of the SEGMENTS section: GCOM_DATA PRELOAD FIXED GCOM_TEXT PRELOAD FIXED A portion of the ROVERLAY.EXP file would appear as follows: CLAICEP_TEXT PRELOAD CLAFIXED_DATA PRELOAD GCOM_DATA PRELOAD FIXED GCOM_TEXT PRELOAD FIXED Please do not take the above change lightly or forget to make it. Failure to add the above lines will cause your program to crash as soon as the communications routines are swapped out of memory. This is especially important for Protected Mode programs as you want the Communications routines to remain FIXED in memory. You may also copy this file to your application's directory, giving it the name of your application with the .EXP extension: APPNAME.EXP. Adding the above lines to your Export file will not, in any way, interfere with applications that do not use CLACOM. Page 8 GAP Communications CLACOM Communications Interface CLACOM supports three serial port interfaces: STANDARD DIGIBOARD INT14/EBIOS The standard interface is used when working with the standard COM1 thru COM4 serial ports on the Host computer. This will be the interface most often used. If an end user is using a DigiBoard then either the DigiBoard or Int14/EBIOS interface may be selected. Most DigiBoard users will use the Int14/EBIOS interface. All input/output to the DigiBoard is performed via Interrupt 14 calls and a Device Driver (supplied by DigiBoard) handles the interface between the program and the board. The DigiBoard interface uses Direct Programming. CLACOM talks to the board directly without the need for a Device Driver. In order to use this interface, a program called RESETDIG.EXE must be used in the AUTOEXEC.BAT file to reset the DigiBoard once when the computer is first booted. This program is supplied as part of the CLACOM package and may be freely distributed to your end users. In order to determine which interface your end users require, you should provide a Hardware screen similar to the following: SCREEN NOT AVAILABLE IN TEXT BASED DOCUMENTATION SEE EXAMPLE PROGAM If the Standard Interface is selected, the Ports Button should be enabled, the DigiBoard Button disabled, and if the Ports Button is selected, a screen similar to the following should be displayed: SCREEN NOT AVAILABLE IN TEXT BASED DOCUMENTATION SEE EXAMPLE PROGAM Page 9 GAP Communications CLACOM If the DigiBoard or Int14/EBIOS Interface is selected, the Ports Button should be disabled, the DigiBoard Button enabled, and if the DigiBoard Button is selected, a screen similar to the following should be displayed: SCREEN NOT AVAILABLE IN TEXT BASED DOCUMENTATION SEE EXAMPLE PROGAM On the Hardware Screen, if the DigiBoard or Int14/EBIOS Interface is selected, then the Port Radio Buttons should be disabled. On the Port Assignments Screen, the Base and IRQ fields for COM 1 and COM 2 should be marked as "Skip". The reason for this is that it makes no difference what a user types into these fields since the standard Base Address and IRQ for these two ports will be used. On the DigiBoard Parameters Screen, the fields that need to be disabled depend upon the Interface. If the Interface is DigiBoard, then the Memory Window and I/O Port Buttons are valid, as is the Channel Number field. Channel Numbers for the Direct Interface generally range from 1 to 16. The sample screens show the valid Window and I/O Port address for a DigiBoard. If, however, the Interface is Int14/EBIOS, the Memory Window and I/O Port Buttons should be disabled. Only the Channel Number field should be selectable. The Int14/EBIOS Interface uses the DigiBoard supplied Device Driver and it already knows what the addresses for the board are, so these Radio Buttons are not needed for this Interface. Channel numbers for this Interface generally range from 4 to 19 (0 - 3 are reserved for COM1 - COM4). Don't try to do range checking on the DigiBoard Channel Numbers. These boards are produced in several varieties from 2 ports, 8 ports, up to 16 ports. An end user that is using a DigiBoard will likely know what Channel Number is being configured. When using the DigiBoard Interface an end user that is using a DigiBoard will also know what Memory Window and I/O Port address the board was configured for when the board was installed. The valid addresses are contained in the DigiBoard manuals and are shown on the sample screens. Page 10 GAP Communications CLACOM Keep in mind that in order to use the DigiBoard Direct Interface, your end users must run the supplied RESETDIG.EXE program in their AUTOEXEC.BAT files. This program makes sure the DigiBoard is reset and able to accept commands when the computer is powered on. It resets all of the Channels on the board, which is why it is run only once. File Transfers CLACOM supports all of the popular File Transfer Protocols. Each of the protocols are given a number (with the exception of Zmodem). Before initiating an Upload or a Download, you need to prompt the user for a Protocol. Your end users won't be the least bit impressed about having to type in a number so your Protocol Browse Box should display Protocol Names. In the background, you will translate the Names into numbers to send to the protocol drivers. The sample Terminal Program shows an excellent example of how to prompt for a Protocol and translate the string into a number to send to the protocol drivers. The Protocols are numbered as follows: 0 - ASCII 3 - 1K Xmodem-G 1 - Xmodem 4 - Ymodem 2 - 1K Xmodem 5 - Ymodem-G Note that as far as CLACOM is concerned, there is no difference between Checksum Xmodem and CRC Xmodem. CLACOM always starts in "CRC Mode" but will adjust itself as necessary. Also note that both of the Ymodem protocols (as well as Zmodem) are Batch Protocols and when Downloading, you need not prompt for a File Name since the name will be supplied by the sender. When Uploading you can either provide a single File Name to upload or a Wild Card specification. Page 11 GAP Communications CLACOM KeyCodes CLACOM includes a function called GetKeyc. If your application needs to send keycodes that were generated from the local keyboard out the Communications Port to a remote computer you need to use this function to gather input from the local keyboard. Clarion's keyboard routines can not be used because Clarion changes the value of certain key presses (including the standard ASCII codes, 0 - 255). For instance, Clarion re-maps the following keys from their standard ASCII value to a value meaningful only to Clarion: Key Clarion Actual Escape 256 27 Enter 257 13 Backspace 258 8 If you use the Clarion keyboard functions and a user presses the backspace key, Clarion returns a code of 258. If you send this keycode to the remote computer, what you will actually be sending is the code 2 (Clarion's keyboard functions return a LONG and Communications Ports can only accept a BYTE, therefore the high bytes of the return value are truncated and only the lower byte is sent). The remote computer will either display the character (a happy face) or act upon it (to the remote computer, it is a Ctrl-B). The remote computer will not know that you were trying to backspace over a previously typed character! Any character typed at the keyboard is a valid character to send out the Communications Port if that character has a value of 255 or less. It shouldn't be re-mapped or translated in any manner. GetKeyc returns keyboard characters "as is". It makes no translations on regular ASCII characters (0 - 255). Any code above 255 (an Extended Keyboard code) returns the actual keyboard scan code for that key with the value 256 added. By adding 256 to the value you can easily determine if the key is an exteneded key. A Backspace is code 8. An Enter is code 13. An Escape is code 27. Because Clarion includes its Keyboard Equate file in your application, there are no supplied mnemonics for the keycodes that GetKeyc returns. Appendix A shows the actual key typed and the value returned by GetKeyc. You can not use BSKey to see if a key press is the Back Space key because of the keyboard re- Page 12 GAP Communications CLACOM mapping equates that Clarion includes in your program. If you do, you will be testing against the code 258 when you need to be testing against the code 8. For instance, this will not work: keychr = GetKeyc() ! Get Key Press if keychr = BSKey ! Backspace hit ComPutc(keychr) ! Actually sends a Ctrl-B end This will work: keychr = GetKeyc() ! Get Key Press if keychr = 8 ! Backspace hit ComPutc(keychr) ! Sends an 8 (backspace) end Page 13 GAP Communications CLACOM Port Initialization The first thing a communications program normally does is initialize the communications port and reset the modem. You will notice that the sample program, GTERM, takes a different approach to the usual "terminal" interface and it doesn't initialize the port until it is ready to use it. How you initialize the communications port depends upon which Interface the user has selected. The DigiBoard and Int14/EBIOS Interfaces set up the port in a single step process. This is because some of the low level routines either in the Int14 Device Driver or the on-board BIOS require that all parameters be known when initializing a port on the board. Setting up the Standard Interface is a two step process. The first step is to set up the Interrupt Handler, program the UART to generate interrupts, turn the FIFO buffers on (if the UART is a 16550) and program the Interrupt Controller chip so that it will recognize the UART interrupts. The second step is to set the Line Control register in the UART. This is more commonly known as setting the Baud Rate, Party, Data, and Stop bits Port Numbers for the Standard and DigiBoard Direct Interface are 0 based. Your users will not be accustomed to entering 0 for COM 1 or 1 for COM 2, therefore your applications should use 1 when referring to COM 1, 2 when referring to COM 2, 3 when referring to COM 3, etc., and you should make the translations to 0 based ports before calling any of the Communications routines. Note that the INT14/EBIOS Interface uses port numbers that begin with 1. The following is an example on setting up the communications port. The first step is to initialize the ANSI driver. This is important so that the screen output functions know how large your Terminal Screen is and the default color you want to use. You must pass the COM port number that the ANSI driver will be associated with. The ANSI Cursor Position Report (CPR) sequence is issued whenever the driver receives a Device Status Report (DSR) command. The CPR sequence is sent out the COM port. Since there is only one screen and one ANSI driver, the driver must know which port to use. The DSR/CPR sequences are generally only used by BBS programs to determine if the caller has ANSI capability. The second step is to determine which Interface the user is using and setup the port accordingly: Page 14 GAP Communications CLACOM InitAnsi(comport,MaxRows,MaxCols,14) ! Initialize Ansi Driver BaudRate = DEFORMAT(GCN:BaudRate) ! string to number data = deformat(GCN:Data) ! get Data stop = deformat(GCN:Stop) ! Stop if GCN:Parity = 'Odd' ! and Parity parity = 1 elsif GCN:Parity = 'Even' parity = 2 else parity = 0 end gotdigi = 0 ! assume no DigiBoard if clip(GCN:Interface) = 'DigiBoard' ! using DigiBoard comport = GCN:DigiChnl - 1 ! 0 base the Port # gotdigi = 1 ! set DigiBoard flag anystring = GCN:DigiSeg ! get Memory Window digiseg = StrHex(anystring) ! as a Hex Number anystring = GCN:DigiPort ! get I/O Port digiport = StrHex(anystring) ! as a Hex Number retcode = DsetUp(DigiSeg,DigiPort,comport,BaudRate parity,data,stop) if retcode > 0 ! display error message and quit end elsif clip(GCN:Interface) = 'Int14/EBIOS' ! using Int14/EBIOS comport = GCN:DigiChnl ! Port Number gotdigi = 1 ! set DigiBoard flag retcode = Int14Set(comport,BaudRate,parity,data,stop) if retcode > 0 ! display error message and quit end Page 15 GAP Communications CLACOM else ! Regular Interface ! get Port, IRQ, and BASE Address IRQ = 0 base = 0 if GCN:Port = 'COM1' comport = 0 elsif GCN:Port = 'COM2' comport = 1 elsif GCN:Port = 'COM3' comport = 2 IRQ = GCN:IRQ3 anystring = GCN:BASE3 base = StrHex(anystring) elsif GCN:Port = 'COM4' comport = 3 IRQ = GCN:IRQ4 anystring = GCN:BASE4 base = StrHex(anystring) end ! initialize COM Port and Interrupt Vector retcode = SetPort(IRQ,base,comport) if retcode > 0 ! display error message and quit else ! Set Baud, Parity, Data, and Stop retcode = InitPort(comport,BaudRate,parity,data,stop) if retcode > 0 ResetPort() ! Interrupts Off ! display error message and quit end end end As you can see when using the Standard Interface and there are no errors setting up the Port, we then call InitPort to set the Baud Rate, Data, etc. Page 16 GAP Communications CLACOM Input & Output To gather input from the local keyboard, GetKeyc is used. GetKeyc returns a SHORT. If the return value is less than 0 then that means no key was pressed (GetKeyc actually returns a -1 in this case). If the return value is greater than 255 then that means an extended key was pressed (function key, cursor pad key, etc). You normally do not send these extended keys out the communications port unless the remote end can accept and handle extended keys. If the remote end can handle extended keys, the usual procedure for sending these keys is to first send a 0, then send the lower 8 bits of the return value. If the return value is less than or equal to 255, then you assign the return value to a BYTE and call ComPutc to send the keyboard code. The following example shows how to use GetKeyc and interpret the return value. Note that we do not use the Clarion KeyCode Equate labels since they are mapped to different codes: comport SHORT retchr SHORT keychr BYTE retchr = GetKeyc() ! get a keyboard character if retchr NOT= -1 ! if something there if retchr > 255 ! Extended Key case retchr ! which one of 278 ! Alt-U, Upload a File of 288 ! Alt-D, Download a File of 369 ! Alt-F10, activate Menu end else ! regular keyboard key keychr = retchr ! Translate to BYTE value ComPutc(comport,keychr) ! and send it out end end Page 17 GAP Communications CLACOM The following example is similar to the above but in this case, the remote end can handle extended keyboard codes: comport SHORT retchr SHORT keychr BYTE retchr = GetKeyc() ! get a keyboard character if retchr NOT= -1 ! if something there if retchr > 255 ! Extended Key case retchr ! which one of 278 ! Alt-U, Upload a File of 288 ! Alt-D, Download a File of 369 ! Alt-F10, activate Menu else ! not something we care about keychr = retchr ! Translate to BYTE value ComPutc(comport,0) ! flag that this is extended key ComPutc(comport,keychr) ! send scan code end else ! regular keyboard key keychr = retchr ! Translate to BYTE value ComPutc(comport,keychr) ! and send it out end end Whether or not local keyboard characters are sent to the local screen depends upon if you originated the connection or answered the connection. Generally the originating side does not display keyboard characters. It simply sends the characters out the communications port and the answering side displays the characters on its screen and sends the characters back, at which time you retrieve them from your receive buffer and display them. This is sometimes refered to as Full Duplex. Some answering systems do not echo characters back to the sender (refered to as Half Duplex). In this case, you will need to display the keyboard character in addition to sending it to the communications port. If you are writing BBS software, you always display locally typed characters on the screen, and you always echo characters received from the communications port back out the port. If you are writing Terminal Emulation software, whether or not to display locally typed characters on the screen is generally a Phone Book option for each entry in the phone book. Characters received from the communications port are never sent back out the port. Page 18 GAP Communications CLACOM The following is an example of keyboard input routines where "Half Duplex" operation is required: comport SHORT retchr SHORT keychr BYTE halfdup BYTE halfdup = 1 ! flag to use half duplex retchr = GetKeyc() ! get a keyboard character if retchr NOT= -1 ! if something there if retchr < 256 ! regular character keychr = retchr ! Translate to BYTE value ComPutc(comport,keychr) ! and send it out if halfdup ! if half duplex Gputc(keychr) ! display on local screen end end end A good example of Half Duplex versus Full Duplex is when you enter into Terminal Emulation mode when not connected with a remote computer. If the modem is configured not to echo characters back, then anything you type will not be displayed on the screen. This is because there is no On Line service on the remote end to send the characters back. If you subsequently place an item on the Terminal Menu to toggle duplex from full to half and toggle it to half, then what you type will be displayed on the screen (providing you write the code to handle this situation, as in the above example). GPutc and GPuts are the local output routines. The first displays single characters while the second displays entire strings. Both routines are tied into the internal ANSI driver which means they can contain ANSI display sequences to move the cursor, change colors, clear the screen, etc. ComGetc is the communications port input routine. It retrieves single byte values from the port. In order to distinguish between a no character available condition (empty receive buffer) and a legitimate character, it returns a negative value (-1) if there are no characters waiting to be read. The return value must be assigned to a BYTE before it can be displayed by Gputc. Page 19 GAP Communications CLACOM An example of ComGetc and Gputc together: comport SHORT retchr SHORT keychr BYTE retchr = ComGetc(comport) ! get a remote character if retchr NOT= -1 ! if something there keychr = retchr ! Translate to BYTE value Gputc(keychr) ! and display it end ComPutc and ComPuts are the communications output routines. The first sends single characters while the second sends entire strings. A word about the built in ANSI driver and Clarion. The ANSI driver writes directly to the video display memory (taking care to honor DESQView's shadow buffer if operating under DESQView). Because Clarion keeps a backup copy of the video display, Clarion will overwrite anything placed on the screen by Gputc and Gputs. This occurs because when Clarion opens a screen or a menu, it first updates the physical screen with the contents of its backup buffer, then opens the screen. The only time this is a problem is when you are in Terminal Mode and using the CLACOM output routines. To circumvent this problem there is a procedure called GetScrn which will update Clarion's backup buffer with the contents of the physical screen. This procedure should be called prior to invoking a Clarion function that writes to the screen. Page 20 GAP Communications CLACOM Sample Application Included with CLACOM is a sample Terminal Emulation program (called GTERM) which shows how to use most of the communications routines. You may use this application as a template for designing your own communications program. The First Procedure is defined as InitProgram. InitProgram first arms a ShutDown Procedure called ResetCbreak. In then makes a call to SetCbreak to set up the Ctrl-Break handler (a necessary requirement for any communications program. ResetCbreak will be called automatically when the program ends. It makes a call to RestCbreak to restore the Ctrl-Break handler. InitProgram then checks to see if the Main Configuration File exists. If this is the first time the program is run, it will create the configuration file with default values for each of the fields. It then checks to see if the Protocol File exists. If not, it creates the file with the 7 internal protocols. This data could be set up in a Memory Queue, but placing it in a file allows you to create an entry screen so that your users can add external protocols. You will see from examining the File Properties that the fields to allow for external protocols are already in the file. If you do create a Browse/Form for adding external protocols, you need to make sure that the user can not delete or change any of the internal protocols. InitProgram then calls MainMenu. On MainMenu the user may select the Files Menu, which contains Quit, to exit the program. The Dial Menu brings up a Lookup screen where the user may select a Phone Number to call. The Dialing Directory is tied into the EditPhone Form so that a user may add or change an entry without having to go to the Setup Menu. When a phone number has been selected, the Dial Procedure initializes the Communications Port and calls the number. Upon successful connection with the remote computer it will place the user in Terminal Mode. Dial gives excellent examples on interfacing with a communications port and a modem. The Terminal Menu puts the user directly into Terminal Mode. Because Terminal Mode can be entered either directly or from the Dial Menu, the procedure checks to see if it was called by Dial. If so, it won't attempt to initialize the Communications Port. If entered from the Menu, Terminal initializes the port in exactly the same manner as Dial, with one exception. For the Port Page 21 GAP Communications CLACOM parameters, instead of using the parameters from a dialing directory entry, it uses the global default parameters. Terminal Mode is really the heart of the application. Whatever is received from the Communications Port is displayed on the screen. Incoming characters are sent to the ANSI Driver. If you wish to emulate a TTY device, instead of sending the characters to the ANSI Driver, you can use Clarion's TYPE function (the character will first have to be converted to a string). Keyboard codes (those entered from the local keyboard) are checked to see if they are extended keys. Any keyboard code above 255 is an extended key. If the key code is a regular keyboard character, it is sent out the Communications Port. If the key code is an extended key it is checked to see if it is the menu activation key (Alt-F10) or one of the "hot keys". If so, the routines associated with those keys are invoked. If the key code is not a regular ASCII character or an extended key that Terminal recognizes it is simply discarded. Please see the section Keycodes for more information on Extended Keyboard Codes and why you need to use CLACOM's GetKeyc function to retrieve characters from the keyboard. Terminal includes a Menu that is activated by pressing the Alt- F10 key. It allows the user to exit Terminal Mode, Upload and Download Files, Clear the Screen, Change Modem Parameters and Hang Up the modem (drop carrier). You will notice that any menu function that depends upon there being a remote carrier is disabled if there is no connection with a remote computer. Because Clarion writes to the screen twice (once to video memory and once to its own backup buffer) Clarion doesn't know that you've been using the ANSI driver to display characters. When you use Gputc and Gputs to send incoming characters to the CLACOM ANSI driver, Clarion has no idea that you've been writing to the screen. While in Terminal Mode, before you call any Clarion Function that displays something on the screen (with the possible exception of the TYPE function) you need to update the backup buffer that Clarion writes to. This is accomplished with a call to GetScrn. GetScrn reads the contents of the physical screen and updates Clarion's backup buffer with the information. Terminal shows how and when to call GetScrn. If you don't make the call to GetScrn then Clarion will erase whatever is on your Terminal Screen before it displays the screen you open. To get a better understanding for this, comment out all of the calls to GetScrn in the Terminal Procedure. Then make and run the program. Make a connection to a remote computer. While in Terminal Mode, activate Page 22 GAP Communications CLACOM the Menu (Alt-F10). Watch what is on the screen suddenly disappear! The Setup Menu allows a user to set default Modem Parameters and enter Phone Book entries. The Modem Parameters are used as the defaults for each Phone Book entry and when entering Terminal Mode from the Terminal Menu. GTERM gives excellent examples on how to use the CLACOM functions and procedures. It can be used as a template to write powerful Terminal Emulation programs that include more terminal emulations, external protocols, script files (for automating logons), keyboard macros, Compuserve or BBS Message handling, Screen Capturing, and lots more. GTERM can be condensed so that your Mailing List Application can automatically dial a number contained in the data base. It can be expanded to become a popular Term program, even a BBS program! Global Variables The following variables are declared global and may be used by your application to alter the behavior of the Communications routines: noascmes When set to 1, disables all messages and windows associated with ASCII file transfers. This is useful when you are using the ASCII upload/download routines for something other than transferring files. nocts When set to 1, disables the Clear To Send (CTS) checking that is performed by the Communications Output routines. Should never be set unless there is a specific reason for doing so. asciidel The number of clock tics to delay after sending each line in a file when using the ASCII file transfer. 18 tics equals 1 second. Page 23 GAP Communications CLACOM Functions - Quick Reference CkeyPress - Checks for a remote or local key press. ClrBuf - Clear the communications receive buffer. ComGetc - Gets a character from com port. ComGetd - Gets a character from com port with time-out. ComPutb - Sends a buffer of data to com port. ComPutc - Sends a character to com port. ComPuts - Sends a string to com port. CursorOff - Turns local cursor off. CursorOn - Turns local cursor on. DclrTx - Clear DigiBoard Transmit buffer. DgtTxfree - Get Free space in DigiBoard Transmit buffer. Dmodem - Change DigiBoard Port parameters. DownLoad - Download using Xmodem and Ymodem. Drestore - Reset DigiBoard Port. DsetUp - Initialize DigiBoard Port (Direct Interface). Dtr - Toggles the DTR line on or off. GetKeyc - Gets keyboard character and scan code. GetScrn - Update Clarion's screen buffer. GetZmodem - Download using Zmodem. Gputc - Sends a character to local screen. Gputs - Sends a string to local screen. InitAnsi - Initializes ANSI driver. InitPort - Sets up Communications Port (Std Interface). Int14Set - Initialize DigiBoard Port (Int14/EBIOS Intface). Iscd - Checks if there is a Carrier. ModemPuts - Send a string to the modem. ModemStat - Get Modem Status. PosCursor - Update ANSI Driver Cursor Position. ResetPort - Restores Communications Port (Std Interface). RestCbreak - Restores Ctrl-Break vector. Rts - Toggles RTS line on or off. Rxempty - Checks if any characters in receive buffer. SendBreak - Send a break signal to the modem. SendZmodem - Send files using Zmodem. SetPort - Initializes Communications port. SetCbreak - Initializes Ctrl-Break vector. StrHex - Translate Hex String to number. StrWord - Find substring in string. Timer - Time Delay. UpLoad - Send files using Xmodem and Ymodem. Page 24 GAP Communications CLACOM Functions - Detailed Reference Functions return a value, procedures do not return anything. Procedures cannot be used in assignment statements. They perform a service and do not report back as to the successful completion of that service. Functions also perform a service but they do report back on how well that service was performed. The return value from a function must be assigned to a variable of like type or used in a comparison statement (this is due to Clarion's strong type checking which will not allow you to call a function without checking its return value). The function descriptions will note whether or not a function is actually a Procedure (does not return a value) or a Function (does return a value). The Examples will use a string called "cstr" to let you know that the function requires a string in the C, NULL terminated, format (CSTRING in Clarion). Passing Clarion Strings to these functions will not work. You will need to assign the Clarion STRING to a CSTRING and then pass the variable in the function call. Page 25 GAP Communications CLACOM CkeyPress ----------------------------------------------------------------- Purpose Checks for a remote or local key press. CkeyPress(port) SHORT port COM Port Number Type Function - Returns SHORT Description This function will check the local keyboard as well as the communications receive buffer to see if a key is waiting to be read. It is most often used in loops that need to wait for a key press, either from remote or local. Return Value 0 = no key is waiting, 1 = a key is waiting. Example c = CkeyPress(0) ! key pressed? loop while CkeyPress(0) = 0 ! do nothing end ! until a key is pressed Page 26 GAP Communications CLACOM ClrBuf ----------------------------------------------------------------- Purpose Clears the Communications receive buffer. ClrBuf(port) SHORT port COM Port Number Type Procedure Description Empties the receive buffer such that any pending characters are simply ignored. Return Value None. Example ClrBuf(0) ! clear Rec Buf (COM 1) Page 27 GAP Communications CLACOM ComGetc ----------------------------------------------------------------- Purpose Retrieve a character from communications buffer. ComGetc(port) SHORT port COM Port Number Type Function - Returns SHORT Description Checks the communications receive buffer and returns the next character, if any. In order to distinguish between a legitimate character and a "no character" condition, this function returns a SHORT even though a legitimate character is a BYTE. If the function does not return a -1, the return value needs to be assigned to a variable of type BYTE if the character is to be passed to a function that requires a BYTE parameter (Gputc and ComPutc, for instance). Return Value Next character in buffer or -1 for no characters waiting. Example c = ComGetc(0) ! get a char from remote keychr BYTE retchr SHORT comport SHORT comport = 0 ! use COM 1 retchr = ComGetc(comport) ! get a char from remote if retchr NOT= -1 ! anything there? keychr = retchr ! yes, truncate high byte Gputc(keychr) ! and display end Page 28 GAP Communications CLACOM ComGetd ----------------------------------------------------------------- Purpose Retrieve a character from communications buffer with delay. ComGetd(port,secs) SHORT port COM Port Number SHORT secs Number of seconds to wait Type Function - Returns SHORT Description This function is the same as ComGetc, except that if there are no characters in the receive buffer, it will wait for the number of seconds you specify. Return Value Next character in buffer or -10 for time-out (no characters to read). Example comport SHORT comport = 0 ! use COM 1 do while ComGetd(comport,2) = -10 ! wait 2 seconds end ! for a character Page 29 GAP Communications CLACOM ComPutb ----------------------------------------------------------------- Purpose Sends a buffer of data out the communications port. ComPutb(port,buffer,len) SHORT port COM Port Number CSTRING buffer Buffer containing data SHORT len Number of bytes to send Type Procedure Description This function will send a user supplied buffer of len bytes out the communications port, one byte at a time. Return Value None. Example buffer CSTRING(200) ComPutb(0,buffer,100) ! Send 100 bytes to COM 1 Page 30 GAP Communications CLACOM ComPutc ----------------------------------------------------------------- Purpose Sends a single character out the communications port. ComPutc(port,ch) SHORT port COM Port Number BYTE ch Character to send Type Procedure Description Will send a single character out the communications port. Return Value None. Example ComPutc(0,13) ! Send a Carriage Return keychr BYTE retchr SHORT comport SHORT comport = 0 ! use COM 1 retchr = GetKeyc ! Keyboard hit? if retchr NOT= -1 ! anything there? if retchr < 256 ! yes, if regular char keychr = retchr ! truncate high byte ComPutc(comport,keychr) ! and send it to remote end end Page 31 GAP Communications CLACOM ComPuts ----------------------------------------------------------------- Purpose Sends a string of characters out the communications port. ComPuts(port,str) SHORT port COM Port Number CSTRING str String to send Type Procedure Description Will send a string of characters out the communications port. Note that unlike ComPutb, the number of bytes to send is determined by the length of the string. Therefore this function stops sending characters when it encounters the NULL byte. Return Value None. Example comport SHORT cstr CSTRING(100) comport = 0 ! use COM 1 cstr = 'Send this String' ! string to send ComPuts(comport,cstr) ! send string to com port Page 32 GAP Communications CLACOM CursorOff ----------------------------------------------------------------- Purpose Turns the local cursor off. CursorOff() Type Procedure Description This function is used to turn the cursor on the local monitor off. Return Value None. Example CursorOff() ! turn the cursor off CursorOn ----------------------------------------------------------------- Purpose Turns the local cursor on. CursorOn() Type Procedure Description This function is used to turn the cursor on the local monitor on. Return Value None. Example CursorOn() ! turn the cursor on Page 33 GAP Communications CLACOM DclrTx ----------------------------------------------------------------- Purpose Clears the Transmit Buffer on DigiBoard. DclrTx(port) SHORT port COM Port (Channel) Number Type Procedure Description When using a DigiBoard (Interface is set to DigiBoard or Int14/EBIOS), this function will clear the Transmit Buffer for the specified port on the DigiBoard. Return Value None. Example DclrTx(4) ! clear xmit buffer Page 34 GAP Communications CLACOM DgtTxfree ----------------------------------------------------------------- Purpose Returns number of Free Bytes in Digi Transmit Buffer. DgtTxfree(port) SHORT port COM Port (Channel) Number Type Function - Returns USHORT Description When using a DigiBoard (Interface is set to DigiBoard or Int14/EBIOS), this function returns the number of free bytes in the Transmit Buffer for the specified port on the DigiBoard. Return Value None. Example freebytes USHORT freebytes = DgtTxfree(4) ! get free space Page 35 GAP Communications CLACOM Dmodem ----------------------------------------------------------------- Purpose Initialize Digi port to baud, parity, data, and stop bits Dmodem(port,baud,parity,data,stop) SHORT port COM Port (Channel) Number LONG baud BPS rate SHORT parity 0 = None, 1 = Odd, 2 = Even SHORT data 6, 7, or 8 data bits SHORT stop 1 or 2 stop bits Type Procedure Description Changes the current port settings on a DigiBoard to the parity, data bits, stop bits, and baud rate. The port number is defined when initially setting up the port with a call to DsetUp or Int14Set. The port parameters are normally set when first initializing the DigiBoard port. This function allows you to change those parameters while "on- line". Return Value None. Example Dmodem(4,2400,2,7,1) ! E,7,1 - 2400 bps Page 36 GAP Communications CLACOM DownLoad ----------------------------------------------------------------- Purpose Receives one or more files. DownLoad(port,protocol,filename) SHORT port COM Port Number SHORT protocol Number of protocol to use CSTRING filename Name of file to download Type Procedure Description This function allows you to receive a file from a remote computer. The protocols are defined as follows: 0 = ASCII 3 = 1K Xmodem-G 1 = Xmodem 4 = Ymodem 2 = 1K Xmodem 5 = Ymodem-G Filename is a CSTRING containing the name of the file to download. If the protocol is a batch protocol (Ymodem or Ymodem-G) then you may pass a NULL string (cstr = '') since the name of the file will be supplied by the remote sender. If a filename is passed, it will be ignored. Return Value None. Example cstr CSTRING(100) cstr = 'FILE.ZIP' ! receive a single file DownLoad(0,2,cstr) ! using 1K Xmodem _ cstr = '' ! receive 1 or more files DownLoad(0,4,cstr) ! using Ymodem Page 37 GAP Communications CLACOM Drestore ----------------------------------------------------------------- Purpose Reset Modem attached to a DigiBoard Port. Drestore() SHORT port COM Port (Channel) Number Type Procedure Description This function simply turns off the handshaking lines to the modem. It turns DTR and RTS off and disables Hardware Flow control. Should be used only when using the DigiBoard or Int14/EBIOS Interface. Return Value None. Example Drestore(4) ! Reset Modem Page 38 GAP Communications CLACOM DsetUp ----------------------------------------------------------------- Purpose Initialize Digi port to baud, parity, data, and stop bits. DsetUp(base, port, channel, baud, parity data, stop) USHORT base Memory Window USHORT port I/O Port SHORT channel Channel Number (port) LONG baud BPS rate SHORT parity 0 = None, 1 = Odd, 2 = Even SHORT data 6, 7, or 8 data bits SHORT stop 1 or 2 stop bits Type Function - Returns SHORT Description When using a Communications Interface set to DigiBoard, this function initializes the specified port (Channel) on the DigiBoard. The DigiBoard Interface is a direct link to the DigiBoard (a Device Driver is not needed). In order to use this interface, the end user must have already run the DigiBoard Reset program called RESETDIG.EXE. The base address is the high memory address the DigiBoard uses when communicating with the host computer. Valid base addresses are: C000 D000 C800 D800 The port is the I/O port the DigiBoard is attached to. Valid ports are: 100 220 110 300 120 320 200 Page 39 GAP Communications CLACOM The channel is the Communications Port to use on the DigiBoard. This should be 0 - 15. Note that base and port are USHORTS. Because it is difficult to gather input from an end user such that the result is a valid hexadecimal number, these two fields are generally stored as strings. You can use the function StrHex to convert a Hexadecimal String to an unsigned short. Return Value 0 = Successful. 1 = DigiBoard not Installed or RESETDIG.EXE not run. 2 = DigiBoard not Responding. 3 = Invalid Parameter passed. 4 = DigiBoard EPROM is too old. Example ! set up 1st port on DigiBoard (Channel = 1) ! DigiBoard Memory Address = D800 ! DigiBoard I/O Port = 320 digiseg USHORT digiport USHORT cstr CSTRING(12) cstr = 'D800' ! Base Address digiseg = StrHex(cstr) ! as a number cstr = '320' ! I/O Port digiport = StrHex(cstr) ! as a number if DsetUp(digiseg,digiport,1,38400,0,8,1) ShowError('Unable To Initialize DigiBoard') end Page 40 GAP Communications CLACOM Dtr ----------------------------------------------------------------- Purpose Toggle the DTR line on or off. Dtr(port,how) SHORT port COM Port Number SHORT how 0 = Turn DTR off 1 = Turn DTR on Type Procedure Description This routine is used to turn the DTR line of the communications port on or off. Turning DTR off while there is a carrier will cause the modem to drop carrier. In order to send commands to the modem, DTR needs to be on. Return Value None. Example cstr CSTRING(10) cstr = 'ATZ' & '<13>' ! Modem Init String Dtr(0,1) ! turn DTR on,wake up modem ComPuts(0,cstr) ! reset the modem Page 41 GAP Communications CLACOM GetKeyc ----------------------------------------------------------------- Purpose Gets keyboard character and scan code. GetKeyc() Type Function - Returns SHORT Description This is the main keyboard input routine. It returns the keyboard character or if the key struck was an extended key, it will return a unique code. These codes are described in Appendix A. This function should be used when designing terminal emulation software, BBS software or any software where you will be checking the local keyboard and the Com Port for key presses. Clarion's ASK and KEYCODE functions cannot be used since Clarion re-maps extended keys and some control keys. Any character in the ASCII range of 0 to 255 is a valid character and can be sent out the Com Port, however Clarion re-maps some of these characters and does not return their true byte value. If the return value is greater than 255, then the key that was pressed is an Extended Key (i.e., F1, Up-Arrow, PgUp, Home, etc). The Extended Key corresponds to the Keyboard Scan codes with the value 256 added. Return Value ASCII code for the key pressed or a unique code for extended keys. Example retchr SHORT retchr = GetKeyc() ! get a keyboard char if retchr > 255 ! Extended Key case retchr ! which one of 278 ! Alt-U, Upload a File of 288 ! Alt-D, Download a File of 369 ! Alt-F10, activate Menu end end Page 42 GAP Communications CLACOM GetScrn ----------------------------------------------------------------- Purpose Copies Physical Screen to Clarion Screen Buffer. GetScrn() Type Procedure Description Clarion keeps a backup copy of the physical screen in a buffer. Whenever you send something to the screen by either opening a Window, a Menu, or what have you, Clarion performs two operations: it updates the physical screen and its screen buffer. The screen output routines in CLACOM (Gputc and Gputs) write directly to the physical screen memory. Clarion, therefore, doesn't know that the screen has been written to. When you open a Window or a Menu, Clarion will re-draw the screen with whatever happens to be in its Screen Buffer and then open your Window. What Clarion puts on the screen will not necessarily be what you see on your physical screen. Clarion only knows about what it wrote to the physical screen. It knows nothing about what an outside function might have put on the screen. If you are using the CLACOM routines to write to the screen and you need to open a Clarion Window, activate a Menu, or otherwise write to the local screen using a Clarion function, you need to call GetScrn before making your Clarion call. GetScrn will copy the contents of the Physical Screen to the Clarion Screen Buffer. This will prevent Clarion from overwriting the physical screen with data that no longer belongs there. Return Value None. Page 43 GAP Communications CLACOM Example keychr BYTE retchr SHORT retchr = GetKeyc() ! Keyboard hit? if retchr = -1 ! nothing there goto getrmt ! check remote end keychr = retchr ! strip high byte if set if retchr < 256 ! if not a scan code ComPutc(0,keychr) ! send to com port goto getrmt ! and check remote end ! Keyboard key was an Extended key. Check if special key ! First though, it is likely that we will be doing something ! that will use Clarion to write to the Screen (open Window, ! Menu, etc). If so, we have to read the physical screen and ! update Clarion's Screen Buffer. This is because Clarion ! doesn't know that our ANSI driver has been writing to the ! screen. If we don't do this, Clarion will erase whatever is ! on the screen right now. GetScrn() ! update Clarion Screen Buffer Page 44 GAP Communications CLACOM ! Note that we already know the key is an extended key so we ! are only checking the low byte of the key (same as ! subtracting 256 from the return value). case keychr ! get special keys of 22 ! Alt-U, Upload A File if online = 0 ! if no carrier, you can't upload ! This is one reason for GetScrn. Remove the call to ! GetScrn and watch what happens when following window ! is opened. Open(NotOnLine) ! Tell um can't upload bell() ! Make noise Beep(0,300) ! Wait 3 seconds Close(NotOnLine) ! Close Can't Upload Screen else ! otherwise, upload away UpFile end end Page 45 GAP Communications CLACOM GetZmodem ----------------------------------------------------------------- Purpose Receives 1 or more files using the Zmodem Protocol. GetZmodem(port) SHORT port COM Port Number Type Procedure Description This function allows you to receive one or more files using Zmodem. The files will be placed in whatever directory the program happens to be in at the time of the call. You may want to use SETPATH to change into a work directory prior to the call. Return Value None. Example GetZmodem(0) ! Receive using Zmodem Page 46 GAP Communications CLACOM Gputc ----------------------------------------------------------------- Purpose Sends a single character to local screen. Gputc(ch) BYTE ch Character to send Type Procedure Description This is one of the main output routines. It is part of the ANSI driver. It will send a single character to the local screen. Return Value None. Example Gputc(12) ! Clear the Screen retchr SHORT keychr BYTE retchr = GetKeyc() ! Keyboard hit? if retchr NOT= -1 ! if something there keychr = retchr ! truncate high byte Gputc(keychr) ! and display it end Page 47 GAP Communications CLACOM Gputs ----------------------------------------------------------------- Purpose Sends a string of characters to local screen. Gputs(str) CSTRING str String to send Type Procedure Description This is one of the main output routines and is part of the ANSI driver. It will send a string of characters to the local screen. Return Value None. Example cstr CSTRING(100) cstr = 'This is a string of characters' Gputs(cstr) ! Display locally ComPuts(0,cstr) ! and to remote ! this example embeds the CR/LF pair at the beginning ! and end of the string cstr = '<13,10>' & 'This is a string of characters' & '<13,10>' Gputs(cstr) ! Display locally Page 48 GAP Communications CLACOM InitAnsi ----------------------------------------------------------------- Purpose Initialize ANSI driver. InitAnsi(port,row,col,color) SHORT port COM Port Number BYTE row Number of Rows on Screen BYTE col Number of Columns on Screen BYTE color Default Color to use Type Procedure Description This function sets up the ANSI driver so that it knows the maximum number of Rows and Columns on the Screen and the default color to use when displaying characters. This function must be called prior to using the output routines Gputc and Gputs. Since the ANSI driver writes directly to Video Memory, it is imperative that this function be called so that it can set internal variables that tells it where the cursor is, the color attribute to use when displaying characters and the Segment address of Video Memory. You should call this function anytime the Screen is changed in size (i.e., from 25 to 43 line mode). The ANSI driver always protects the bottom row of the screen. In other words, it will not allow text to be written there using Gputc or Gputs. If you need to write to the bottom screen row, use the Clarion SHOW function. The color parameter is a standard IBM color code in the range of 0 to 255. The Color codes are described in the Clarion Language Reference Manual in the Video and Keyboard Chapter. You must pass the COM port number that the ANSI driver will be associated with. The ANSI Cursor Position Report (CPR) is issued whenever the driver receives a Device Status Report (DSR) command. The CPR sequence is sent out the COM port. Since there is only one screen and one ANSI driver, the driver must know which port to use. The DSR/CPR sequences Page 49 GAP Communications CLACOM are generally only used by BBS programs to determine if the caller has ANSI capability. Return Value None. Example MaxRows SHORT MaxCols SHORT MaxRows = ROWS() ! Get Max Number of Rows MaxCols = COLS() ! Get Max Number of Columns SetCursor(1,1) ! Cursor to top of screen InitAnsi(0,MaxRows,MaxCols,14) ! Initialize ANSI driver Page 50 GAP Communications CLACOM InitPort ----------------------------------------------------------------- Purpose Initialize port to baud, data, parity, and stop bits. InitPort(port,baud,parity,data,stop) SHORT port COM Port Number LONG baud BPS rate SHORT parity 0 = None, 1 = Odd, 2 = Even SHORT data 6, 7, or 8 data bits SHORT stop 1 or 2 stop bits Type Function - Returns SHORT Description Sets the communications port to the parity, data bits, stop bits, and baud rate. The port number is defined when initially setting up the port with a call to SetPort. This function should only be used when the Communications Interface is set to Standard. Don't call when interfacing with a DigiBoard. Return Value 0 = Successful. 1 = Port Not Initialized. 2 = Invalid Parameter. Example if InitPort(0,38400,0,8,1) ! Initialize to N,8,1 - 38400 bps ShowError('Unable To Initialize Port') end Page 51 GAP Communications CLACOM Int14Set ----------------------------------------------------------------- Purpose Initialize Digi port to baud, parity, data, and stop bits. DsetUp(channel,baud,parity,data,stop) SHORT channel Channel Number (port) LONG baud BPS rate SHORT parity 0 = None, 1 = Odd, 2 = Even SHORT data 6, 7, or 8 data bits SHORT stop 1 or 2 stop bits Type Function - Returns SHORT Description When using a Communications Interface set to Int14/EBIOS, this function initializes the specified port (Channel) on the DigiBoard. This interface requires that the end user have the DigiBoard supplied Universal DOS Driver installed as a TSR. The channel is the Communications Port to use on the DigiBoard. This should be 4 - 19. Return Value 0 = Successful. 1 = Device Driver not installed or DigiBoard not installed. 2 = EBIOS not configured. 3 = Invalid Parameter passed. Example ! set up 1st port on DigiBoard (Channel = 4) if Int14Set(4,38400,0,8,1) ShowError('Unable To Initialize DigiBoard') end Page 52 GAP Communications CLACOM Iscd ----------------------------------------------------------------- Purpose Check for Carrier on the Communications Port. Iscd(port) SHORT port COM Port Number Type Function - Returns SHORT Description This function allows you to test the communications port for a remote carrier signal. Return Value Returns 0 if there is no carrier and 1 if there is a carrier. Example if Iscd(0) ! is there a carrier? online = 1 show(MaxRows,MaxCols - 7,' OnLine') else online = 0 show(MaxRows,MaxCols - 7,'OffLine') end Page 53 GAP Communications CLACOM ModemPuts ----------------------------------------------------------------- Purpose Sends a Command String to a Modem. ModemPuts(port,str) SHORT port COM Port Number CSTRING str String to send Type Procedure Description Will send a string of characters out the communications port. This function is generally used to send commands to a modem. It is identical to ComPuts except that it interprets and acts upon certain characters. The special characters are: ^M - Send a Carriage Return ~ - Tilde. Pause for 1/2 second Note that the special characters are not sent to the modem. Also note that in order for a modem to accept commands, the modem must be "offline" (not connected to a remote modem) and DTR must be set : Dtr(1). Return Value None. Example cstr CSTRING(100) cstr = 'ATZ^M~~' ! Modem Reset String ! The above string will send the Modem Reset String followed ! by a Carriage Return. It will wait 1 second after sending ! the string. ModemPuts(0,cstr) ! Send Modem Command Page 54 GAP Communications CLACOM ModemStat ----------------------------------------------------------------- Purpose Returns Status of the attached Modem. ModemStat(port) SHORT port COM Port Number Type Function - Returns BYTE Description Returns the value of the Modem Status Register. Return Value None. Example modstat BYTE modstat = ModemStat(0) ! get Modem Status if BAND(Modstat,080h) ! check for Carrier online = 1 ! got one, set flag else online = 0 ! no carrier, reset flag end Page 55 GAP Communications CLACOM PosCursor ----------------------------------------------------------------- Purpose Restore ANSI Driver Cursor Position. PosCursor() Type Procedure Description When opening a window and then closing it, Clarion does not put the cursor back where it was prior to opening the window. This doesn't cause any problems because the ANSI driver maintains its own internal cursor position. However, the screen will look a bit strange if the cursor is "hanging" in the middle of the screen when it should be on row 2, column 10. Return Value None. Example PosCursor() ! Put Cursor back where it was Page 56 GAP Communications CLACOM ResetPort ----------------------------------------------------------------- Purpose Restores the Communications port. ResetPort(port) SHORT port COM Port Number Type Procedure Description This function must be called prior to exiting the program or anytime you are finished with the Com Port. It restores the interrupt vector used by the Standard Communications routines. It is imperative that when using the Standard Interface you call this function when you no longer wish to access the Serial Port. The Standard Interface sets up an interrupt vector for the port and if this vector is not restored prior to exiting your program, the computer will ultimately crash. This function should only be used when the Communications Interface is set to Standard. Don't call when interfacing with a DigiBoard. Return Value None. Example ResetPort(0) ! Reset COM 1 Page 57 GAP Communications CLACOM RestCbreak ----------------------------------------------------------------- Purpose Restores the Ctrl-Break vector. RestCbreak() Type Procedure Description This function must be called prior to exiting the program. It restores the interrupt vector used by the Ctrl-Break routine. If you set up a Ctrl-Break handler at the beginning of your program, you should call this function from a SHUTDOWN procedure. Setting up a SHUTDOWN procedure insures that the Ctrl-Break vector is restored prior to program termination. Return Value None. Example RestCbreak() ! restore Ctrl-Break vector Page 58 GAP Communications CLACOM Rts ----------------------------------------------------------------- Purpose Toggle the RTS line on or off. Rts(port,how) SHORT port COM Port Number SHORT how 0 = Turn RTS off 1 = Turn RTS on Type Procedure Description This routine is used to turn the Request To Send line of the communications port on or off. Turning RTS off (providing the modem supports hardware handshaking) tells the modem to stop sending data to the computer. It is typically toggled off while writing a buffer of data to a disk. Return Value None. Example Rts(0,0) ! Turn RTS off Page 59 GAP Communications CLACOM Rxempty ----------------------------------------------------------------- Purpose To check if there are any characters in the receive buffer. Rxempty(port) SHORT port COM Port Number Type Function - Returns SHORT Description This function checks the communications receive buffer to see if there are any characters waiting to be read. Return Value Returns 1 if buffer is empty, 0 if there are characters waiting to be read. Example while Rxempty(0) ! nothing happening end ! wait till something to read Page 60 GAP Communications CLACOM SendBreak ----------------------------------------------------------------- Purpose Sends a Break Signal to Modem. SendBreak(port) SHORT port COM Port Number Type Procedure Description Will send a Break Signal to the Modem. This function is most often used with high speed modems that have their own transmit buffer and you wish to clear the buffer. These modems can be configured to empty their buffer upon receipt of a break signal. Note that some modems do not react too well to a break signal. Whether or not to send a break to the modem so that you can clear its transmit buffer should be a configuration option. Return Value None. Example SendBreak(0) ! Send a Break to Modem Page 61 GAP Communications CLACOM SendZmodem ----------------------------------------------------------------- Purpose Sends one or more files using Zmodem. SendZmodem(port,filename) SHORT port COM Port Number CSTRING filename Name of file to upload Type Procedure Description This function allows you to send one or more files to a remote computer using the Zmodem Protocol. Filename is a CSTRING containing the name of the file to upload. It may contain a Wild Card Specification to send more than one file at a time. Return Value None. Example cstr CSTRING(100) cstr = 'FILE.ZIP' ! send a single file SendZmodem(0,cstr) cstr = '*.ZIP' ! send all the ZIP files SendZmodem(0,cstr) Page 62 GAP Communications CLACOM SetCbreak ----------------------------------------------------------------- Purpose Initializes the Ctrl-Break vector. SetCbreak() Type Procedure Description To trap Ctrl-C and Ctrl-Break, this function should be called to set up an interrupt service routine to trap these two keys. It is imperative that the program not exit before calling RestCbreak so that the interrupt vector can be restored. When using the Standard Communications Interface, a Ctrl-Break vector must be installed to prevent a user from breaking out of your program before you've had a chance to restore the Communications Interrupt vector. Return Value None. Example SetCbreak() ! set up Ctrl-Break ISR Page 63 GAP Communications CLACOM SetPort ----------------------------------------------------------------- Purpose Initialize the Communications Port. SetPort(irq,base,port) SHORT irq Port IRQ to use SHORT base Port Base Address to use SHORT port Com Port Number Type Function - Returns SHORT Description This is the port initialization routine that must be called when using the Standard Interface. It must be called prior to any port I/O calls. IRQ is the Interrupt Request number to use for the port. Base Address is the address where the port is located. Port is the COM port number, where COM1 = 0, COM2 = 1, COM3 = 2, and COM4 = 3. For COM 1 and COM 2, you may simply pass 0 as the IRQ and Base address since the defaults for these ports will be used. Note that the Communications Routines always use hardware handshaking. This means that if CTS is not active, the output routines will not be able to send a character out the serial port. CTS is normally controlled by a Modem, however when not using a modem, the serial cable must be wired so that CTS on one end of the connection is tied to RTS on the other end. See Appendix B for a diagram of a NULL Modem cable. Return Value 0 = successful. 1 = No UART found at Port Address. 2 = Clear To Send (CTS) is not active. Example ! Set Up Port on COM1 if SetPort(0,0,0) ShowError('Unable To Initialize Port') end Page 64 GAP Communications CLACOM StrHex ----------------------------------------------------------------- Purpose Converts a Hexadecimal string to an Unsigned Short. StrHex(hexstring) CSTRING hexstring String containing Hex digits Type Function - Returns USHORT Description This function will convert a string containing hexadecimal digits and return the value of that string as an unsigned short. It is most often used to convert Memory Addresses stored as a string to a number that can be utilized by the port initialization routines. Return Value 0 if string could not be converted, number if it could. Example cstr CSTRING(100) hexnum USHORT cstr = 'D800' ! Base Address hexnum = StrHex(cstr) ! as a number Page 65 GAP Communications CLACOM StrWord ----------------------------------------------------------------- Purpose Check if one string contains another string. StrWord(srcstring,substring) CSTRING srcstring String to search CSTRING substring String to search for Type Function - Returns SHORT Description Clarion's INSTRING function doesn't work very well with C strings (in fact, it doesn't work at all). The terminating NULL seems to be included as part of the search value. StrWord will search for a string to see if it is contained within another string. Both strings must be of type CSTRING. If the larger string contains the smaller string, the position in the larger string where the smaller string begins will be returned. Note that the strings are compared without regard to case. Return Value 0 if substring not found, otherwise position in source string where the substring starts. Example srcstring CSTRING(100) substring CSTRING(10) scrstring = 'This is a string' substring = 'string' if StrWord(srcstring,substring) ! srcstring contains substring else ! substring not found end Page 66 GAP Communications CLACOM Timer ----------------------------------------------------------------- Purpose Pauses for the number of "ticks" specified. Timer(ticks) SHORT ticks Number of timer ticks to pause Type Procedure Description This function allows you to pause all processing for the specified number of ticks. It is in- sensitive to processor speed. The function simply delays the number of "ticks" indicated by the passed parameter. Each tick is 1/18 of a second (or 55 milliseconds). Return Value None. Example Timer(18) ! pause for 1 second Page 67 GAP Communications CLACOM UpLoad ----------------------------------------------------------------- Purpose Sends one or more files. UpLoad(port,protocol,filename) SHORT port Com Port Number SHORT protocol Number of protocol to use CSTRING filename Name of file to upload Type Procedure Description This function allows you to send a file to a remote computer. The protocols are defined as follows: 0 = ASCII 3 = 1K Xmodem-G 1 = Xmodem 4 = Ymodem 2 = 1K Xmodem 5 = Ymodem-G Filename is a CSTRING containing the name of the file to upload. If the protocol is a batch protocol (Ymodem or Ymodem-G) then you may pass a Wild Card Specification to send more than one file at a time. Return Value None. Example cstr CSTRING(100) cstr = 'FILE.ZIP' ! send a single file UpLoad(0,2,cstr) ! using 1K Xmodem cstr = '*.ZIP' ! send all the ZIP files UpLoad(0,4,cstr) ! using Ymodem Page 68 GAP Communications CLACOM Appendix A GetKeyc obtains keyboard input by making calls to the Computer BIOS. The BIOS translates keyboard scan codes into unique codes. Any code returned by GetKeyc that is less than or equal to 127 is a regular ASCII character. Codes in the range of 128 to 255 are IBM enhanced ASCII characters. These codes are returned "as is" (no translations are performed upon them). Key Codes greater than 255 present a problem. These are extended keys and include the function keys, cursor keys, and the Ctrl and Alt key combinations. The BIOS returns the scan code of these keys. The problem is that the scan code can lie in the range of ASCII characters (0 through 255). In order to distinguish between a displayable ASCII character and an extended key (F1, Home, PgDn, Alt-Equal, etc), GetKeyc adds 256 to the key code returned by the BIOS. The following tables show the extended key codes as well as Control Key combinations (which are used extensively in communications). Page 69 GAP Communications CLACOM Control Keys and Extended Keys in Numerical Order: Ctrl-A 1 Alt-S 287 Shift-F9 348 Ctrl-B 2 Alt-D 288 Shift-F10 349 Ctrl-C 3 Alt-F 289 Ctrl-F1 350 Ctrl-D 4 Alt-G 290 Ctrl-F2 351 Ctrl-E 5 Alt-H 291 Ctrl-F3 352 Ctrl-F 6 Alt-J 292 Ctrl-F4 353 Ctrl-G 7 Alt-K 293 Ctrl-F5 354 Backspace 8 Alt-L 294 Ctrl-F6 355 Ctrl-H 8 Alt-Z 300 Ctrl-F7 356 Ctrl-I 9 Alt-X 301 Ctrl-F8 357 Tab 9 Alt-C 302 Ctrl-F9 358 Ctrl-J 10 Alt-V 303 Ctrl-F10 359 LineFeed 10 Alt-B 304 Alt-F1 360 Ctrl-K 11 Alt-N 305 Alt-F2 361 Ctrl-L 12 Alt-M 306 Alt-F3 362 Ctrl-M 13 F1 315 Alt-F4 363 Enter 13 F2 316 Alt-F5 364 Ctrl-N 14 F3 317 Alt-F6 365 Ctrl-O 15 F4 318 Alt-F7 366 Ctrl-P 16 F5 319 Alt-F8 367 Ctrl-Q 17 F6 320 Alt-F9 368 Ctrl-R 18 F7 321 Alt-F10 369 Ctrl-S 19 F8 322 Ctrl-PrintScreen 370 Ctrl-T 20 F9 323 Ctrl-CursorLeft 371 Ctrl-U 21 F10 324 Ctrl-CursorRight 372 Ctrl-V 22 Home 327 Ctrl-End 373 Ctrl-W 23 CursorUp 328 Ctrl-PgDn 374 Ctrl-X 24 PgUp 329 Ctrl-Home 375 Ctrl-Y 25 CursorLeft 331 Alt-1 376 Ctrl-Z 26 CursorRight 333 Alt-2 377 Escape 27 End 335 Alt-3 378 BackTab 271 CursorDown 336 Alt-4 379 Alt-Q 272 PgDn 337 Alt-5 380 Alt-W 273 Insert 338 Alt-6 381 Alt-E 274 Delete 339 Alt-7 382 Alt-R 275 Shift-F1 340 Alt-8 383 Alt-T 276 Shift-F2 341 Alt-9 384 Alt-Y 277 Shift-F3 342 Alt-0 385 Alt-U 278 Shift-F4 343 Alt-Hyphen 386 Alt-I 279 Shift-F5 344 Alt-Equal 387 Alt-O 280 Shift-F6 345 Ctrl-PgUp 388 Alt-P 281 Shift-F7 346 Alt-A 286 Shift-F8 347 Page 70 GAP Communications CLACOM Control Keys and Extended Keys in Alphabetical Order: Alt-0 385 Alt-V 303 Ctrl-T 20 Alt-1 376 Alt-W 273 Ctrl-U 21 Alt-2 377 Alt-X 301 Ctrl-V 22 Alt-3 378 Alt-Y 277 Ctrl-W 23 Alt-4 379 Alt-Z 300 Ctrl-X 24 Alt-5 380 Backspace 8 Ctrl-Y 25 Alt-6 381 BackTab 271 Ctrl-Z 26 Alt-7 382 Ctrl-A 1 CursorDown 336 Alt-8 383 Ctrl-B 2 CursorLeft 331 Alt-9 384 Ctrl-C 3 CursorRight 333 Alt-A 286 Ctrl-CLeft 371 CursorUp 328 Alt-B 304 Ctrl-CRight 372 Delete 339 Alt-C 302 Ctrl-D 4 End 335 Alt-D 288 Ctrl-E 5 Enter 13 Alt-E 274 Ctrl-End 373 Escape 27 Alt-Equal 387 Ctrl-F 6 F1 315 Alt-F 289 Ctrl-F1 350 F10 324 Alt-F1 360 Ctrl-F10 359 F2 316 Alt-F10 369 Ctrl-F2 351 F3 317 Alt-F2 361 Ctrl-F3 352 F4 318 Alt-F3 362 Ctrl-F4 353 F5 319 Alt-F4 363 Ctrl-F5 354 F6 320 Alt-F5 364 Ctrl-F6 355 F7 321 Alt-F6 365 Ctrl-F7 356 F8 322 Alt-F7 366 Ctrl-F8 357 F9 323 Alt-F8 367 Ctrl-F9 358 Home 327 Alt-F9 368 Ctrl-G 7 Insert 338 Alt-G 290 Ctrl-H 8 LineFeed 10 Alt-H 291 Ctrl-Home 375 PgDn 337 Alt-Hyphen 386 Ctrl-I 9 PgUp 329 Alt-I 279 Ctrl-J 10 Shift-F1 340 Alt-J 292 Ctrl-K 11 Shift-F10 349 Alt-K 293 Ctrl-L 12 Shift-F2 341 Alt-L 294 Ctrl-M 13 Shift-F3 342 Alt-M 306 Ctrl-N 14 Shift-F4 343 Alt-N 305 Ctrl-O 15 Shift-F5 344 Alt-O 280 Ctrl-P 16 Shift-F6 345 Alt-P 281 Ctrl-PgDn 374 Shift-F7 346 Alt-Q 272 Ctrl-PgUp 388 Shift-F8 347 Alt-R 275 Ctrl-PrtScr 370 Shift-F9 348 Alt-S 287 Ctrl-Q 17 Tab 9 Alt-T 276 Ctrl-R 18 Alt-U 278 Ctrl-S 19 Page 71 GAP Communications CLACOM Appendix B Most of the Null Modem connectors and cables that are commercially available are wired incorrectly. Sounds unbelievable, but true. They are wired using yesterday's technology. Modern day modems are intelligent devices. They are capable of telling the Host Computer when to stop sending data and are able to determine when the computer needs to have data sent to it temporarily suspended. This concept is known as Hardware Flow Control (CTS/RTS checking). CLACOM was written with Hardware Flow Control in mind. No characters will be sent to the communications port if the port is unable to accept new characters. This prevents loss of data and insures a reliable connection. Most NULL Modems are wired with the CTS/RTS lines either always off or always on. If you are hardwiring computers together via a NULL Modem, you will probably have to change some of the wiring on the connectors. You can either make your own NULL Modem or purchase one. If you purchase one, be sure that you can remove the connector shields to gain access to the wiring. The following diagram shows a properly wired NULL Modem: SCREEN NOT AVAILABLE IN TEXT BASED DOCUMENTATION SEE PRINTED MANUAL Page 72 GAP Communications CLACOM Index Ansi driver 5, 19, 20, 22, 24, 44, 47, 48, 56 Initializing 14, 24, 49 Asciidel 23 ASK 42 Base Address 10, 64 Baud Rate 5, 36, 39, 51, 52, 64 Channel 10, 11, 39, 40, 52 Characters Sending to com port 17, 24, 31 Sending to local screen 17, 24, 47 CkeyPress 24, 26 Clarion ASK 42 Color 49 CSTRING 25, 32, 37, 40, 41, 48, 54, 62, 65, 66, 68 Cursor 56 INSTRING 66 KEYCODE 12, 42 Overlays 8 ROVERLAY.EXP 8 Screen 56 Screen Buffer 20, 43 SHOW 49 Strings 66 TYPE 22 Type Checking 25 ClrBuf 24, 27 Color 49 ComGetc 19, 24, 28 ComGetd 24, 29 Communications Base address 14, 64 Baud rates 5, 14, 64 Carrier 53 DigiBoard 9, 14, 51, 57 FIFO buffers 5, 14 Initializing 14, 36, 39, 51, 52, 64 Input 28, 29, 60 Interface 9, 51, 57 Interrupt 8, 14, 57 IRQ 64 Output 30, 31, 32, 54 Port 9, 64 Page 73 GAP Communications CLACOM ComPutb 24, 30 ComPutc 20, 24, 31 Computs 20, 24, 32 CSTRING 25, 32, 37, 40, 41, 48, 54, 62, 65, 66, 68 Ctrl-Break handler 8, 58, 63 CTS 64 Cursor 24, 33, 56 CursorOff 24, 33 CursorOn 24, 33 DclrTx 24, 34 Delaying 67 DgtTxfree 24, 35 DigiBoard 9, 51, 57 Channel 10, 11, 39, 40, 52 Initializing Port 14, 36, 39, 52 Resetting Modem 38 Transmit Buffer 34 Free Space 35 Distribution files 6 Dmodem 24, 36 DownLoad 24, 37 Downloading Files 11, 37, 46 Drestore 24, 38 DsetUp 14, 24, 36, 39 Dtr 24, 41 Files Downloading 11, 37, 46 Uploading 11, 62, 68 Functions CkeyPress 26 ClrBuf 27 ComGetc 19, 28 ComGetd 29 ComPutb 30 ComPutc 20, 31 ComPuts 20, 32 CursorOff 33 CursorOn 33 DclrTx 34 DgtTxfree 35 Dmodem 36 DownLoad 37 Drestore 38 DsetUp 14, 36, 39 Dtr 41 GetKeyc 12, 42, 69 GetScrn 43 GetZmodem 46 Page 74 GAP Communications CLACOM Gputc 19, 43, 47, 49 Gputs 19, 43, 48, 49 InitAnsi 14, 49 InitPort 14, 51 INSTRING 66 Int14Set 14, 36, 52 Iscd 53 ModemPuts 54 ModemStat 55 PosCursor 56 ResetPort 57 RestCbreak 58 Rts 59 Rxempty 60 SendBreak 61 SendZmodem 62 SetCbreak 63 SETPATH 46 SetPort 14, 51, 64 SHOW 49 SHUTDOWN 58 StrHex 40, 65 StrWord 66 Timer 67 UpLoad 68 GetKeyc 12, 24, 42, 69 GetScrn 24, 43 GetZmodem 24, 46 Gputc 19, 24, 43, 47, 49 Gputs 19, 24, 43, 48, 49 Hardware Handshaking 64 InitAnsi 14, 24, 49 Initializing ANSI driver 49 Interrupt handlers 64 InitPort 14, 24, 51 Input From com port 17, 24, 28, 29, 60 From local & remote 17, 26 From local keyboard 12, 17, 24, 42, 69 INSTRING 66 Int14Set 14, 24, 36, 52 Interrupt handlers Communications 8, 14, 57 Ctrl-Break 8, 58, 63 IRQ 10, 64 Iscd 24, 53 Keyboard 12, 17, 26, 42, 69 Page 75 GAP Communications CLACOM Clarion Key Codes 12, 42 KEYCODE 12, 42 Modem 38, 41, 51, 72 Sending strings to 54 ModemPuts 24, 54 ModemStat 24, 55 Noascmes 23 Nocts 23 NULL Modem 64, 72 Output To com port 17, 24, 30, 31, 32 To local screen 17, 24, 47, 48 To modem 54 Overlays 8 Pausing 67 Port 9, 14, 34, 35, 36, 38, 39, 41, 51, 64 PosCursor 24, 56 Program Crashing 8 Protocols 5, 11, 21, 23, 37, 46, 68 External 21, 23 Receive buffer 24, 26, 27, 28, 29, 60, 64 RESETDIG.EXE 9, 11, 39, 40 ResetPort 24, 57 RestCbreak 24, 58 ROVERLAY.EXP 8 Rts 24, 59, 64 Rxempty 24, 60 Scan codes 42 Screen 24, 43, 47, 48, 49, 56 Clearing 47 Color 49 Columns 49 Cursor 33 Output 17 Rows 49 Screen Buffer 20, 43 SendBreak 24, 61 SendZmodem 24, 62 SetCbreak 24, 63 SETPATH 46 SetPort 14, 24, 51, 64 SHOW 49 SHUTDOWN 58 Standard Interface 9, 14, 51, 57, 64 StrHex 24, 40, 65 Strings 66 Hexadecimal 40 Page 76 GAP Communications CLACOM INSTRING 66 Sending to com port 24, 32, 54 Sending to local screen 24, 48 Sub string 66 StrWord 24, 66 Timer 24, 67 Transmit Buffer 24, 34 Free Space 35 TYPE 22 UpLoad 24, 68 Uploading Files 11, 62, 68 Video Memory 43 Xmodem 5, 11, 24, 37, 68 Ymodem 5, 11, 24, 37, 68 Zmodem 5, 11, 46, 62 Page 77