Simtel MSDOS 1992 June

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

/ Simtel MSDOS 1992 June / SIMTEL_0692.cdr / msdos / sysutl / superv22.arc / SUPER.DOC < prev next >

Wrap

Text File | 1986-12-18 | 21.2 KB | 551 lines

SUPERCOM resident Int 14 driver Version 2.0 (C) Copyright 1986, 1987 Doctor Debug Pittsburgh, Pa All Rights Reserved As with all the Doctor's software, SUPERCOM has been tested and by all indications works as described under all reasonable conditions. However, the good doctor cannot be responsible for damages, heartbreak, outbreaks of war or acts of God caused by the use of this software. As it is Shareware, distribution of this package is encouraged so long as the programs and documentation are unaltered. Please read the contribution information at the end of this document. This document will give the command syntax and function descriptions for SUPERCOM version 2.0. It will also highlight the differences between Version 1 and Version 2. WHAT IS SUPERCOM AND WHAT IS IT DOING ON MY COMPUTER? SUPERCOM is a replacement for the normal BIOS interrupt 14, which handles asynchronous communications. The support through BIOS is so pitifully inadequate that it is almost impossible to write secure, reliable communications software using the four functions they give you. SUPERCOM gives you 16 useful functions and a variable length receive buffer. It has been designed with interface to high level languages in mind, and in fact includes Turbo Pascal procedures to utilize all of SUPERCOM's functions. HOW DO I RUN SUPERCOM? SUPER.COM must be run before any applications program can use it, for it attaches itself to BIOS. .pa COMMAND SYNTAX: SUPER [/I] [/Cnn] [/X] WHERE: /I indicates that SUPERCOM is to function in Interrupt Mode. The default is Polling Mode, which was the only method available in version 1. (See below for a description of these modes). /Cnn sets the size, in K, of SUPERCOM's receive buffer. (Default = 4K). SuperCom will accept anything from 1 to 99, but buffer sizes above 60K will cause unpredictable results. /X enables XON/XOFF processing. If SUPERCOM receives an XOFF (^S) over the active COM port, all transmits are suspended until an XON (^Q) is received. This is an extremely useful device as well as an extremely dangerous one. If no XON is received, your system is hung. Typing an Alt Q from the keyboard will clear this condition. NOTE: The XON and XOFF characters are not placed in the receive buffer. Note that simply typing SUPER and pressing Enter will load SUPERCOM in exactly the same configuration as Version 1. You will be given a message which indicates that SUPERCOM is loaded and your system prompt will return. At this point your computer will behave entirely normal. It is like a big car with a Turbocharger in it - the extra power isn't used until you activate it. You activate SUPERCOM and utilize its many features via normal INT 14 calls. Below is a lit of the functions available and what they do. Function 0 - Set Communications Parameters Entry: AH = 0 AL = Initialization parameters (Same as original INT 14) Return: Status returned in AX Notes: This works exactly like the old INT 14 function 0, and in fact is called by SUPERCOM function 12. Do not use this function to initialize the port; use function 12. However, if you wish to change the line parameters (baud rate, parity, etc) after the SUPERCOM port has been opened, use this function to prevent disconnection. .pa Function 1 - Send Character Entry: AH = 1 AL = Character to Send Return: High bit of AL set if error occurred Notes: There is no fundamental difference between this function and the original INT 14 Function 1. Function 2 - Receive Character Entry: AH = 2 Return: AL has character. AH is zero unless error occurred. Notes: This will timeout after about 6 seconds. Function 3 - Port Status Entry: AH = 3 Return: Status returns in AH and AL as in old INT 14. Function 4 - Clear Buffer Entry: AH = 4 Return: None Note: Empties the receive buffer. Function 5 - Block Receive Entry: AH = 5 DX = Port (0 or 1) CX = Size of desired block ES:BX = address for data Return: Specified number of characters placed in [ES:BX] AH nonzero if error occurred. Note: Will time out as in Function 2. The Checksum calculation (formerly returned in CX) is no longer supported. Function 6 - Block Send Entry: DX = port (0 or 1) CX = size of block ES:BX = Address of data to send Return: AX will have status codes .pa Function 7 - Buffer status Entry: AH = 7 Return: BX = number of characters waiting in receive buffer Function 8 - Get Character Entry: AH = 8 DX = Port (0 or 1) Return: If character is available in buffer, it is returned in AL. If no characters are waiting, AL returns as 0 (nul). Note: Character is removed from the receive buffer. If there is a chance there will be nuls in the receive data, use function 7 to determine whether a character is available. This is the equivalent of INKEY$ for the Com port. Function 9 - Set Port Entry: AH = 9 DX = Port (0 or 1) to buffer Return: none Note: Use this to switch ports in mid-stream. Use Function 12 to set the port initially. Function 10 (0AH) - Enable/Disable SUPERCOM Entry: AH = 0A Return: None Note: Used internally - use Functions 12 and 13 to accomplish this function. This function toggles whether SUPERCOM is active or inactive. If inactive, all INT14 calls go to original BIOS interrupt. Function 11 (0BH) - SUPERCOM Active Status Entry: AH = 0B Return: AH = 1 if SUPERCOM Active AH = 0 if SUPERCOM Inactive (passing calls to BIOS) Note: Again, mainly for internal use, but if you need a quick check use this. .pa Function 12 (0CH) - Open SUPERCOM port Entry: AH = 0C AL = Initialization Parameters (as in Function 0) DX = Port (0 or 1) Return: AX will have status codes Notes: This is how you activate SUPERCOM and enable all the features. If you need to change some line parameters (baud rate, parity, etc.) while the SUPERCOM port is open, use Function 0. Function 13 (0DH) - Close SUPERCOM port Entry: AH = 0DH DX = Port (0 or 1) Return: None Notes: This disables buffering of incoming characters and removes either the timer interrupt or the Comm interrupt from the system interrupt chain. Be sure your program performs a Close before exiting, especially if you are using Receive Polling. Function 14 (0EH) - Peek Buffer Entry: AH = 0E Return: If a character is available in the buffer it is returned in AL, but IS NOT removed from the buffer. If no character is available, AL returns as a nul. Note: This allows you to look ahead at the next character and decide what to do before removing that character from the buffer. Function 15 (0FH) - Hello (*NEW*) Entry: AH = 0F Return: AX = 0AAAH Note: Why? If 0AAA doesn't come back, SUPERCOM isn't loaded. Handy to prevent sudden departures for the Twilight Zone. .pa Function 16 (10H) - Kill SUPERCOM (*NEW*) Entry: AH = 10 Return: None Note: This is the equivalent of Close Port (Function 13) with a twist. Not only is the port closed, SUPERCOM is removed entirely from the interrupt chain and the memory which was used is deallocated (returned to DOS). This function is ONLY for use if SUPERCOM is loaded by the application (as opposed to being loaded before the application) and no other resident programs were loaded after it. Improper use of this function will wear out your on/off switch. (The technique of post-loading is discussed below). If used properly, this function will make the system as it was before SUPERCOM was loaded. GENERAL NOTES: I have attempted to keep with the general philosophy of the other BIOS interrupts, thus error returns and such will be in line with the original INT 14 and the other interrupts. The buffering is done much like the BIOS keyboard interrupt does it. SUPERCOM returns error codes in AH and AL (unless they are returning other information). These error codes will be the same as those returned by the standard Input/Output routines of the old Interrupt 14. All this is pretty complicated, which is why I have included the file SUPERCOM.PAS, which contains turbo Pascal routines which access these functions. DUMBTERM.PAS is a demonstration program which is essentially a plain vanilla comm program. Examining these programs will provide some insight into how SUPERCOM works. Be sure to compile any Turbo programs using SUPERCOM to a .COM file before using! DUMBTERM.COM has been included for those out there without a Turbo Pascal Compiler. Also included is DUMB.ASM and DUMB.COM, which are essentially the same thing as DUMBTERM.PAS only in 8086 assembler. .pa ADVANCED TOPICS I - WHATS WITH THE /I? There are two methods fpr SUPERCOM to detect and buffer incoming characters. The default method, and the one used exclusively in version 1, I call Receive Polling. Instead of relying on the system interrupt structure to notify SUPERCOM of an incoming character, SUPERCOM itself checks for incoming characters at a rate of almost 5000 times per second (plenty fast for 9600 baud, and even fast enough for 19.2). This single technique (which is used in no other package that I am aware of) accounts for the high reliability of SUPERCOM. Alas, this also accounts for nearly all the problems users have had with SUPERCOM. This method can cause problems in the following ways: 1) If the SUPERCOM port is not closed before a return to the operating system, the system will behave very unpredictably. Some PCs have been known to spout Poe and Longfellow when this happens; others just break down and start crying from the tension. Make damn sure there is no way short of re-booting that the user can end the program without a ClosePort. 2) Non-standard hardware such as screen blankers and turbo boards can cause compatibility problems. 3) Not quite IBM compatible systems can also see compatibility problems as well as psychological trauma. If SUPERCOM will run in default mode without problems, I suggest that you let it run that way. It is so much more reliable and less prone to character drops that it is indeed worth the precautions. If however you wish to trade gee-whiz for same-old-stuff run SUPER with the /I switch. This enables Receive Interrupt mode which sets up the interrupt structure as described above. It will work fine except you will find 9600 baud communications strained to the limit if you are on a network or have a bunch of memory resident time wasters loaded. It will not mess with the system clock or interval timer. ADVANCED TOPICS II - HOW DO I POST_LOAD SUPERCOM? SUPERCOM was designed to be a resident program which could be placed in an AUTOEXEC.BAT file and thus be Pre-Loaded. There has been great public outcry (from at least 3 people) for a method of allowing an application to load SUPERCOM, use the functions, and then remove SUPERCOM when the program was finished. This version of SUPERCOM will allow you to do this, but please follow the steps outlined below and be very careful. This procedure has been tested and works well. 1) Your application program must load SUPER.COM with the DOS EXEC function call. If you are using a high level language such as Compiled Basic which cannot do this sorry, you cannot post-load SUPERCOM. 2) When control passes back to your application, you will have full use of SUPERCOM's features. You must not load any other programs during this time. SUPERCOM will be sitting in memory above your application and will be perfectly safe until you harass it. 3) When the communications are finished, execute SUPERCOM function 16 to Kill SUPERCOM and remove all vestiges of it from DOS's knowledge. It is recommended that you keep SUPERCOM post-loaded for only as long as you need it. There is no danger or penalty from doing multiple loads and kills of SUPERCOM as long as it is done in the above manner. Another drawback is that your compiler or system gets to muck about with the system timers, etc. before SUPERCOM gets there, therefore you may have to use the Receive Interrupt mode when postloading. The only way to know is to try it. If SUPERCOM drops characters by the handful in Receive Polling mode, you will have to use the /I when loading SUPERCOM. I have included the Turbo Pascal source file POSTLOAD.PAS to demonstrate how to use this feature. .pa ADVANCED TOPICS III - SUPERCOM Pascal Routines The routines discussed below are found in the file SuperCom.Pas. Please reference that file for more information. These routines are meant to be called by user programs. The SUPER.COM Interrupt 14 driver must have been installed to use any of these routines. Use of these routines without proper installation of SUPER.COM will produce unpredictable results. It should be relatively simple to translate these turbo routines into C or most any other language. The integers InError and OutError will always contain the error conditions after every receive or transmit. The bits of these values are defined as: Bit 7 (128) Timeout Bit 3 (8) Framing Error Bit 2 (4) Parity Error Bit 1 (2) Overrun Error If the value of InError[port] is 0, then you can be sure that the last character was received without error. The value or Port is always 1 or 2. Procedure InitPort(port,Baud,Parity,data_bits,stop_bits) Baud: integer 300-9600 Parity: char, E(ven),O(dd),N(one) Data_bits: integer, 7 or 8 Stop_bits: integer, 1 or 2 This routine initializes the communications port to the parameters specified and activates SUPERCOM for that port. All of the following functions will use the port specified here. .pa Function PortStatus(port) This function returns the line status and modem control status of the comm port specified. The bits returned are defined as: Bit 15 (negative) Time out (no device connected) Bit 14 (16384) Transmission shift register empty Bit 13 (8192) Transmission holding register empty Bit 12 (4096) Break detect Bit 11 (2048) Framing error Bit 10 (1024) Parity error Bit 9 (512) Overrun error Bit 8 (256) Data ready Bit 7 (128) Received line signal detect Bit 6 (64) Ring indicator Bit 5 (32) Data set ready Bit 4 (16) Clear to send Bit 3 (8) Delta receive line signal detect Bit 2 (4) Trailing edge ring detector Bit 1 (2) Delta data set ready Bit 0 (1) Delta clear to send Procedure XmitCh(ch) This Procedure sends the character in ch out the port specified. Procedure XmitBlk(string) This procedure sends the entire string out the comm port. Procedure XmitLn(string) This is identical to XmitBlk, but adds a CR/LF to the end of the block. Procedure RecCh(ch) This procedure waits until a character is available over the comm line and then returns it in ch. If the system times out ch will contain a nul (Ascii 0). Procedure RecLn(string) This is the equivalent of ReadLn over the comm port. Be sure to check the InError variable to make sure the operation did not time out (no CR was received.) .pa Procedure RecBlk(number,String) The number of characters specified by number will be placed into the string. Be sure to check the InError variable to assure that the operation did not time out before sufficient characters were received. Procedure GrabCh(ch) If a character is waiting in the receive buffer it will be returned in ch otherwise ch will contain a nul character. Procedure PeekBuff(ch) Identical to GrabCh but the character is not removed from the buffer. Procedure ClearBuff Empties the receive buffer Procedure ClosePort Closes the comm port and deactivates SUPERCOM until the next InitPort. Function Rlen Returns the number of characters currently available in the receive buffer. Function SupercomPresent Returns true if SUPERCOM has been loaded, false otherwise. Procedure KillPort Closes the comm port and removes SUPERCOM completely. Use this function only if you have performed a post-load. .pa Summary (How to use SUPERCOM in a few semi-easy steps) 1) Make sure that SUPER.COM has been run so that SUPERCOM is resident. It is very difficult for software to work properly when in is not in the computer's memory. 2) Your program should first issue an Interrupt 14 with AH set to 12 (opens the port with SUPERCOM) and the other registers set as in the old BIOS Interrupt 14 Function 0. This assures that SUPERCOM is humming away, busily checking comm activity on the port specified. 3) Now you can use the SUPERCOM functions to input or output all the happy data over that comm port. .pa 4) Before exiting the program, issue an Interrupt 14 with AH set to 13 (close SUPERCOM port). This assures that all is back to normal for any programs which you run later. (If you have performed a Post-Load, use function 16 instead of 13 to remove SUPER.COM from memory). *** THE COMMERCIAL *** A great deal of time and effort has gone into the writing of this program, so if you find it useful, please send a contribution of $25.00 (yes its gone up) or whatever you feel it is worth to: Steel City Software 1 Windsor Road B-6 Pittsburgh, PA 15239 If you are going to use SUPERCOM in your own program which you intend to market, this $25.00 is NOT optional, and if you do not pay it, the spirit of disk crashes and chip burnouts will follow you for the rest of your days. Aside from this, paying the fee will make sure that you will be notified of product enhancements, and also any new shareware products being distributed by Steel City Software. Oh yes, a brief mention in the documentation of your product wouldn't hurt either. The source code for SUPER.COM is available for $40.00. It contains a wealth of information about communications, interrupts, and the 8088 in general and is well worth the expenditure. You can contact the doctor at either of the following two BBS's: NeverBoard Fido (412) 733-4842 SoundingBoard Fido (412) 681-9464 The doctor checks these board daily, so you will get a prompt reply to comments, complaints, and suggestions. The most current version of the Doctor's software can be found on these boards at all times.