Simtel MSDOS 1992 June

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

/ Simtel MSDOS 1992 June / SIMTEL_0692.cdr / msdos / qbasic / fossc004.arc / FOSSCOMM.TXT < prev next >

Wrap

Text File | 1988-11-01 | 30.2 KB | 1,292 lines

FossComm version 0.04 August 22, 1988 Program Documentation Copyright (C) 1988 Daan van der Weide All rights reserved FosComm is an interface between a compiled BASIC program and a so-called FOSSIL driver. It enables the user to take advantage of all the functions regarding the communication ports, from a BASIC program. In this way it is possible to avoid the problems/shortcomings of the BASIC communications handler. FossComm is based on the document 'Fundamentals of FOSSIL implementation and use, draft version 5, February 11, 1988' by Rick Moor. Please make sure that your fossil driver meets this draft. FossComm can be used with any of the following compilers : MicroSoft Quickbasic 1.00, 2.00, 3.00 and 4.00, 6.00 IBM BasCom 1.00, 2.00 LICENSE AND REGISTRATION ------------------------ FossComm is distributed as a 'shareware' program. Please help me get it known by giving away unmodified copies of the program and documentation to other people, either by copying the disk or making it available for downloading on a BBS system. FossComm is copyright (C) 1988 by Daan van der Weide. It is not public domain or free software. Non-registered users are granted a limited license to use FossComm on a trial basis for determining whether or not it is suitable for their needs. Registration allows the use of FossComm in programs for sale and/or distribution. The registration fee is 50 guilders (25 US$). Users who pay the registration fee will be sent a disk woth the latest version and documentation ans some example programs. It is also possible to obtain the source codes for FossComm. In that case the registration fee is 100 guilders (50 US$). Register your usage of FossComm by sending the registration fee to : Daan van der Weide Kastelenstraat 229-3 1082 EG Amsterdam the Netherlands telephone : (0)20 463647 Your comments regarding the FossComm program or any suggestions you have for extensions or for other programs that would be useful to you are welcome. ------------------------------------------------------------ FossComm page 2 FossComm Daan van der Weide makes no warranties whatsoever regarding the FossComm computer program or the documentation. USING FOSSCOMM IN YOUR PROGRAMS ------------------------------- The FossComm module contains a number of functions that handle the access of RS232 communication boards as provided by a driver conform the FOSSIL standard. Below follows a list of the functions supported and the parameters that should be specified, as well as the eventual return values. To incorporate the module within your compiled program specify the name FOSSCOMM.OBJ when linking your program. Example : LINK MYPROG+FOSSCOMM,MYPROG; CREDITS ------- I would like to mention a few people who have supported and still are supporting the development : Ronald Koridon who adapted RBBS 16.1a to run using FossComm and who is my primary 'guinea-pig'; Arjen Lentz, John Janssen sysops that are using the RBBS 16.1a FOSSIL version as well. the RBBS version as well to run. (they've probably upgraded by now ...) FEEDBACK -------- As you may know, any software developer depends on his users to modify, adjust and extend his product. Therefore I'm very interested in all comments, notes and critics towards the FossComm product. I can be reached either by telephone or, better, at the RBBS system listed below. Thank you very much ! RBBS Gaasperdam (4 lines) sysop Ronald Koridon Amsterdam, the Netherlands 31 (0)20 978493 node 1 913890 node 2 974420 node 3 972763 node 4 ------------------------------------------------------------ FossComm page 3 FossComm Revision history ---------------- v0.01 This is the first alpha-test version only released to people involved in testing. v0.02 Extended FOSSIL calls implemented to access keyboard and to do video I/O etc. Not released. v0.03 Adaptions according to draft 5 are made. FOSSPEED changed, so that parity, databits and the number of stopbits may be specified as well. The documentation is extended, and a number of functions was added. v0.04 I think the product is solid enough to release it generally, especially because there's 'official' RBBS support for FossComm. A number of BBS systems are running for a few months now without any problems. ------------------------------------------------------------ FossComm page 4 FossComm ------------------------------------------------------------- FOSINIT ------------------------------------------------------------- PURPOSE : Initializes the FOSSIL driver, and checks whether the FOSSIL driver is installed. This function should be called before any other FOS calls are made. DTR is raised by this call. The baudrate is NOT set by this call. FORMAT : FOSINIT(port%, result%) RETURNS : 0 no error, driver initialized -1 error initializing driver EXAMPLE : 100 PORT% = 1 110 CALL FOSINIT(PORT%,RESULT%) 120 IF RESULT% = -1 THEN PRINT "ERROR INITIALIZING FOSSIL" REMARKS : The number of the comport that may be initialized depends on the particular FOSSIL driver you're using. Refer to the documentations of your driver for the values. Should a second call to this function occur, all buffers, flow-contol parameters etc. are reset to their initial state and no error is returned. ------------------------------------------------------------- FOSEXIT ------------------------------------------------------------- PURPOSE : This function should be called whenever the communications port in no longer needed. No FOS calls to the particular comport can be made anymore once this call has been made. DTR is not affected by this call. FORMAT : FOSEXIT(COMPORT%) ------------------------------------------------------------ FossComm page 5 FossComm ------------------------------------------------------------- FOSSPEED ------------------------------------------------------------- PURPOSE : Sets the baudrate and the additional line control parameters for the communication port. If a non-supported baudrate is specified, the baudrate variable is set to -1, and no call to the FOSSIL drive is made. FORMAT : FOSSPEED(comport%, speed%, parity%, databits%, stopbits%) where speed% can be one of the following : 300,600,1200,2400,4800,9600,19200,38400 parity% can be : 0 for no parity 1 for odd parity 2 for no parity 3 for even parity databits% can be : 0 for 5 databits 1 for 6 databits 2 for 7 databits 3 for 8 databits stopbits% can be : 0 for 1 stopbit 1 for 1½ stopbit if databits% = 0 i.e. 5 bits or 2 stopbits for all other values for databits%. RETURNS : speed% is set to -1 if an illegal baudrate was specified, otherwise speed% is not affected. ------------------------------------------------------------ FossComm page 6 FossComm ------------------------------------------------------------- FOSTXCHAR ------------------------------------------------------------- PURPOSE : Transmits a character using the specified port. If there's room in the transmit buffer, the return will be immediate, otherwise it will wait until there is room to store the character in the transmit buffer. FORMAT : FOSTXCHAR(comport%, char%, result%) REMARKS : For the values of the result% parameter, please refer to the description of the FOSSTATUS function. ------------------------------------------------------------- FOSRXCHAR ------------------------------------------------------------- PURPOSE : If there's a character available in the receive buffer, the character will be returned. When no character is available, it will wait until one becomes available. FORMAT : FOSRXCHAR(comport%, char%, result%) REMARKS : For the values of the result% parameter, please refer to the description of the FOSSTATUS function. ------------------------------------------------------------ FossComm page 7 FossComm ------------------------------------------------------------- FOSSTATUS ------------------------------------------------------------- PURPOSE : Requests status information about the state of the comport. FORMAT : FOSSTATUS(comport%, status%) status bits returned are : 15 14 13 12 11 10 09 08 07 06 05 04 03 02 01 00 mask -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- XX XX XX XX XX XX | | | | | | | | | | | | | | | | | + bit is always set | | | | | | | | | +----- Carrier Detect &H0080 | | | | | | | +-------- Input data available &H0100 | | | | | +----------- RX buffer overrun &H0200 | | | +----------------------- Room available &H2000 | +-------------------------- Output buffer empty &H4000 ------------------------------------------------------------- FOSDTR ------------------------------------------------------------- PURPOSE : Raises or lowers the DTR signal on the specified comport. FORMAT : FOSDTR(comport%, state%) state% can be : 0 to indicate that DTR should be lowered 1 to indicate that DTR should be raised ------------------------------------------------------------ FossComm page 8 FossComm ------------------------------------------------------------- FOSTXFLUSH ------------------------------------------------------------- PURPOSE : Forces the transmission of all characters that currently are in the transmit buffer. The function does not return until all characters are transmitted !!! FORMAT : FOSTXFLUSH(comport%) ------------------------------------------------------------- FOSTXPURGE ------------------------------------------------------------- PURPOSE : This function purges all pending characters in the transmit buffer. Any characters not transmitted are discarded. FORMAT : FOSTXPURGE(comport%) ------------------------------------------------------------- FOSRXPURGE ------------------------------------------------------------- PURPOSE : Purges the receive buffer. Any input data in the receive buffer is discarded. FORMAT : FOSRXPURGE(comport%) ------------------------------------------------------------ FossComm page 9 FossComm ------------------------------------------------------------- FOSTXCHARNW ------------------------------------------------------------- PURPOSE : This function is similar to the FOSTXCHAR function, except that if the driver is unable to buffer the character - because the transmit buffer is full - the call returns immediately indicating the success of the call in the result% parameter. FORMAT : FOSTXCHARNW(comport%, char%, result%) result% can be : 0 if the character could *NOT* be transmitted 1 if the character was transmitted ------------------------------------------------------------- FOSREADAHEAD ------------------------------------------------------------- PURPOSE : Peeks into the receive buffer and returns the character that will be returned upon the next FOSRXCHAR call, or returns -1 if the receive buffer is empty. FORMAT : FOSREADAHEAD(comport%, char%) char% is -1 if the receive buffer is empty ------------------------------------------------------------ FossComm page 10 FossComm ------------------------------------------------------------- FOSFLOWCTL ------------------------------------------------------------- PURPOSE : Enables or disables the flow control on the transmission. Two kinds of flow control are supported : 15 14 13 12 11 10 09 08 07 06 05 04 03 02 01 00 -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- XX XX XX XX XX XX XX XX FORCED HIGH | | | | | | | | | | | +-- Xon/Xoff | | | on | | | transmit | | | | | +----- CTS/RTS | | | +-------- DSR/DTR | +----------- Xon/Xoff on receive When the corresponding bit is set, that type of flow control is enabled. Applications should set the upper four bits in the lower nibble as well, i.e. bits 4, 5, 6 and 7. When the bit is cleared, that type of flow control is disabled. Enabling Xon/Xoff on transmission will suspend transmission upon receiving an Xoff character. The FOSSIL drives will resume transmission as soon as an Xon character is received. Enabling CTS/RTS, will suspend transmission when CTS is lowered. As soon as CTS is raised, transmission is resumed. The FOSSIL driver will drop RTS whenever a certain amount of the receive buffer is filled. As soon as the receive buffer contains less characters than the predetermined percentage, RTS is raised again. Enabling DSR/DTR, will suspend transmission when DSR is lowered. As soon as DSR is raised, transmission is resumed. The FOSSIL driver will drop DTR whenever a certain amount of the receive buffer is filled. As soon as the receive buffer contains less characters than the predetermined percentage, RTS is raised again. Enabling Xon/Xoff on receive, will cause the FOSSIL driver to send an Xoff character whenever a certain amount of the receive buffer is filled. An Xon character will be sent, as soon as the receive buffer contains less characters than the predetermined percentage. ------------------------------------------------------------ FossComm page 11 FossComm FORMAT : FOSFLOWCTL(comport%, state%) EXAMPLES : state% is : &H00F0 to disable all flow control types &H00F1 to enable Xon/Xoff on transmission &H00F2 to enable CTS/RTS &H00F4 to enable DSR/DTR &H00F8 to enable Xon/Xoff on reception ------------------------------------------------------------- FOSCTRLCK ------------------------------------------------------------- PURPOSE : Enables/disables extended Ctrl-C/Ctrl-K checking, and/or enables/disables the transmitter. 15 14 13 12 11 10 09 08 07 06 05 04 03 02 01 00 -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- XX XX | | | +--- CtrlCK | +------ TX Bit 0 controls whether the extended Ctrl-K/Ctrl-C checking is enabled (bit set) or disabled (bit not set). Bit 1 controls whether the transmitter is active or not, in the same way Xon/Xoff characters do affect the transmitter. If the extended Ctrl-C/Ctrl-K checking is enabled, any subsequent call to this this routine will return an internal flag maintained by the FOSSIL driver, that indicates whether Ctrl-C/Ctrl-K has been pressed. When enabled, the Ctrl- C/Ctrl-K character does *NOT* appear in the receive buffer. FORMAT : FOSCTRLCK(comport%, state%) EXAMPLES : COMPORT% = 1 STATE% = &H0001 FOSCTRLCK(COMPORT%, STATE%) IF STATE% AND &H0001 THEN PRINT "CTRL-C/CTRL-K RECEIVED" ------------------------------------------------------------ FossComm page 12 FossComm ------------------------------------------------------------- FOSWDOG ------------------------------------------------------------- PURPOSE : Enables or disables 'watchdog' processing. When watchdog is enabled, the state of the carrier detect (DCD) line on the particular comport is constantly monitored, and whenever the signal drops, i.e. the connection is terminated the system is rebooted. This option is typically used in combination with external programs shelled from a main program. The FOSINIT/FOSEXIT calls do *NOT* affect this monitoring. FORMAT : FOSWDOG(comport%, state%) state% = 1 to enable the watchdog process state% = 0 to disable the watchdog process ------------------------------------------------------------- FOSBOOT ------------------------------------------------------------- PURPOSE : Boots the system. This function enables a program to perform either a soft- or a warmboot. FORMAT : FOSBOOT(type%) type% = 0 for a 'cold'start (incl. POST & memory tests) type% = 1 for a 'warm'start (only DOS reboots) ------------------------------------------------------------ FossComm page 13 FossComm ------------------------------------------------------------- FOSREAD ------------------------------------------------------------- PURPOSE : Read a block of data from the receive buffer. The number of characters actually transferred is put into the BYTES% variable after the call. FORMAT : FOSREAD(comport%, bytes%, buffer$) EXAMPLE : ' 'create a 32 byte buffer ' BUF$="12345678901234567890123456789012" ' PORT% = 1 BYTES% = 32 ' CALL FOSREAD(PORT%, BYTES%, BUF$) ' PRINT "BYTES READ : ";BYTES% PRINT "DATA READ : ";LEFT$(BUF$,BYTES%) ------------------------------------------------------------ FossComm page 14 FossComm ------------------------------------------------------------- FOSWRITE ------------------------------------------------------------- PURPOSE : Write a block of data to the transmit buffer. The number of characters actually transferred is put into the BYTES% variable after the call. FORMAT : FOSWRITE(comport%, bytes%, buffer$) EXAMPLES : ' 'create some string ' BUF$="Welcome to MailPro !"+CHR$(10)+CHR$(13) ' PORT% = 1 BYTES% = LEN(BUF$) ' CALL FOSWRITE(PORT%, BYTES%, BUF$) ' PRINT "BYTES WRITTEN : ";BYTES% ------------------------------------------------------------- FOSBREAK ------------------------------------------------------------- PURPOSE : Starts or ends the transmission of a break state. FORMAT : FOSBREAK(comport%, state%) state% = 1 to start a break state% = 0 to end a break ------------------------------------------------------------ FossComm page 15 FossComm ------------------------------------------------------------- FOSTIMERTICK ------------------------------------------------------------- PURPOSE : This function returns information about the current timer interrupt. It returns the interrupt number the timer is tied to, the number of ticks per second, and the number of milliseconds per tick. FORMAT : FOSTIMERTICK(Intno%, Ticks%, Msecs%) ------------------------------------------------------------- FOSSCANKEY ------------------------------------------------------------- PURPOSE : Scans the keyboard and returns the next character in the keyboard buffer. If no characters are available a value of -1 will be returned. The values returned will match the IBM-style of keycoding. FORMAT : FOSSCANKEY(Key%) ------------------------------------------------------------- FOSGETKEY ------------------------------------------------------------- PURPOSE : Returns the next character in the keyboard buffer. If no characters are available, the functions waits until a key is pressed. FORMAT : FOSGETKEY(Key%) ------------------------------------------------------------ FossComm page 16 FossComm ------------------------------------------------------------- FOSLOCATE ------------------------------------------------------------- PURPOSE : Locates the cursor on the screen. The screen is treated to have coördinates as follows : ( 0, 0) +---------------------------------------------+ | | | Hello World, this is supposed to be a | | picture of a screen... | | | | | | | | | | | +---------------------------------------------+ (24,79) FORMAT : FOSLOCATE(Row%, Col%) ------------------------------------------------------------- FOSGETLOC ------------------------------------------------------------- PURPOSE : Returns the current position of the cursor. FORMAT : FOSGETLOC(Row%, Col%) ------------------------------------------------------------ FossComm page 17 FossComm ------------------------------------------------------------- FOSDISPANSI ------------------------------------------------------------- PURPOSE : Displays a character and allows ANSI screen processing to occur (if available). On DOS machines the FOSSIL routine to perform this function probably will call a DOS function to do the ANSI processing. Keep in mind that DOS function are not re-entrant. In such cases, this routine may not be assumed to be re-entrant either. FORMAT : FOSDISPANSI(Char%) ------------------------------------------------------------- FOSDISPBIOS ------------------------------------------------------------- PURPOSE : Displays a charactes using the system BIOS. This means that DOS output redirection does not work when this call is used to produce screen output. FORMAT : FOSDISPBIOS(Char%) ------------------------------------------------------------ FossComm page 18 FossComm