Power-Programmierung

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

/ Power-Programmierung / CD1.mdf / basic / library / qb_pds / communic / asylib / asylib.doc < prev next >

Wrap

Text File | 1988-10-30 | 67.4 KB | 1,589 lines

AsyLIB - Documentation version 1.10 Released October, 1988 -Gizmo Mike I. Introduction AsyLIB is a complete set of primitives for developing telecommunications programs and utilites from QuickBASIC. This library is compatible with QuickBASIC 4.00, 4.00(a) and 4.00(b) as well as the MicroSoft BASIC Compiler 6.00, though we _heartily_ recommend QB 4.00(b) or BC 6.0. Included in the developer's kit are routines for 8 different file transfer protocols, character I/O, ANSI.SYS support, keyboard control, symbolic carriage return support for storing macro files to disk, even a robust script language and a not-so-primitive terminal program to demonstrate some of the functions, as well as many support items. The collection includes both low level and high level routines, with the bulk being in BASIC with many, many support items being in assembler. By supplying things like low level routines to read blocks from disk, there is no dependency on ANY general purpose library collection and therefore, you may not need to buy anything else to get your own terminal programs up and running. However, it must be noted that the addition of things like windows and screen saves, will not only reduce the overall code size and development time, but it will speed up program execution and most of all, will add that flash and dazzle found in most all well written programs. The demo program included is a fully working implementation of a terminal program that simply attempts to demonstrate how easy it is to construct a terminal program of your own with modular, 'callable' telecommunications routines. The key to the ease of use in AsyLIB is that it is totally modular: practically everything is a CALLed sub program that means code is extremely easy to read and program. Further, virtually every function is therefore available throughout the program and you can add only those that you need: if you have a singular purpose application in mind that only needs to support say, Xmodem or Ymodem-G, then you need not wade thru tons of GOTO AND GOSUB code, and waste hours editing out Xmodem1k code and so forth: you simply execute CALLs to those you need and let LINK tie in those that are used. II. License, conditions of use Under no circumstances may these routines be distributed individually or without the accompanying documentation and demo, which are both an integral part of the package, nor may the documentation be altered in anyway. This includes, but is not limited to, distributing ASYLIB.QLB for use in executing applications compiled to BRUN format. Under no circumstances may the routines in the AsyLIB package, source, object files, libraries or documentation be distributed by or otherwise become a part of, or affiliated with any group or organization involved in the distribution of what is generally been come to be known as SHAREWARE for disk or distribution fees, or for fees of any sort without my express WRITTEN consent. This includes supplying the routines, library and or documentation for so-called disk fees. Finally, as the author, I make no claims that the routines herein will fit your needs, simply that in all testing and prior use that they worked for me and that you may find them interesting and helpful in your programming. Any liability for the use, misuse or inability to use the AsyLIB routines or libraries, lies solely with user of AsyLIB. III. AsyLIB A. AsyLIB Compatibility Because QB has built in COM port support, in this case it would be counter productive to replace them, so the majority of the AsyLIB functions are in BASIC. These were written with the MS BASIC Compiler 6.0 and should work equally as well with QB 4.00(b). Note that prior versions (read: QB 4.00 and QB4.00(a)) do have a few com port handling problems. If you are planning to attempt TCOMM related programs, you are strongly urged to upgrade to QB 4.00(b), especially since it is free from MicroSoft. The AsyLIB functions and routines are not suitable for use with versions of QuickBASIC prior to QB 4.00. B. Support As long as it exists, I will support and entertain questions regarding QB, GLIB, DLIB or AsyLib via the QuickBASIC conference on The Information Booth, (316) 684 8744, 1200 - 19200 bps, 24 hrs. This is a "free" BBS, though registration is required. If you have a problem or question on GLIB, DLIB or AsyLIB, PLEASE be prepared to supply some sort of source code to demonstrate your problem. I am more than a little interested in any LIB or QB bugs that you might find, but PLEASE do not waste my time or yours with general, vague inquiries without supporting source examples - I do not need .EXE's. C. License You are granted free and unlimited use of any and all routines in AsyLIB that you may find of value. Furthermore, you are free to pass along the BBS distribution files (the demo and the documentation) as long as they are passed along as a whole according to the guidlines listed above. No one is granted any permission to share or pass along the BCOM library, nor object files or source code. D. Purchase As distributed, the AsyLIB documentation, the demo and the environment library (.QLB) provide you with everything you need to call and execute AsyLIB routines from within the editor/environment. In this manner, the user or programmer is granted unlimited rights for using AsyLIB with QuickBASIC and the supplied .QLB library for personal use either from the QB environment or even in the form of a 'BRUN' style compiled library. This provides an ample forum for purposes of sampling, testing and evaluation and allows unlimited latitude in terms of personal use or as a tutorial regarding some of the more advanced features in today's QuickBASIC. If any of these are your intention, then the files included with this documentation provide everything you need, and you are free to use them in that format without further obligation. However, you might find some of the routines of value and want to incorporate them into a standalone (BCOM type .EXE) application. In this case, the library of routines and permission to use them in such applications can be purchased as described below. This is the best of all worlds: You get unlimited personal and/or evaluation use. If you find it of value, the BCOM library can be purchased. If AsyLIB does NOT fit your needs, then you are 'out' nothing, not even the time to download the .LIB file(s). AsyLIB prices are as follows: BCOM .OBJ / LIB files, only $ 30.00 BCOM .OBJ / LIB and BASIC source $ 55.00 Compare this with "commercial" .LIBS that sell for _TWICE_ as much: The one that goes for $79 and NO SOURCE! The one that runs a whopping $99 and requires another library! The one that costs $129 and supports only XMODEM !!! ...and NONE have a free try out period !!!!! Who pays for those goofy ads they run? YOU DO Regardless of the license level, you get everything in the BBS file collection plus: - A QB or BC LIB containing all the routines documented later, as well as the object files themselves. - An Asynchronous communications overview with an in-depth discussion of all the protocols supported. - A collection of QB4 / TCOMM programming tips and notes based on the AsyDEMO.BAS terminal program provided and various things we encountered in developing AsyLIB. - A Script File to disk routine that allows you to store compiled script files to a file thus precluding the need to link in the script file compile routine, reducing code size and execution time! A complementary routine to read such a compiled file from file back into memory at run time is also provided. To purchase either the AsyLIB Object File/.LIB or the BASIC Source Code library license (ASM source is not supplied): a. Fill out the enclosed mailer, with Cash, check or money order payable in U.S. Funds and mail it to the address supplied on the mailer. b. Orders not accompanied with the mailer/order form will be returned as we need the information requested to correctly fill your order. c. Please allow 3-4 weeks for delivery (I am out of town a LOT). Mailing Address: InfoSoft AsyLIB 1.1 PO Box 782057 Wichita, Ks 67278-2057 IV. Demo program notes The demo program is not meant to be a Procomm or Qmodem replacement. Rather, it is meant as a vehicle to demonstrate some of the basics of QB communications I/O and the functions of the AsyLIB package. In reality, were I to attempt to take on such a task, I would NOT attempt it without a solid general library package to provide support for such things as windows, screen saves and a text input editor. Without it, coding is considerably more tedious and lots less flashy. The demo vehicle, while fully functional, is meant more as a vehicle to demonstrate some of the features in AsyLIB and spur some interest in ideas that could be in a communications program. Some of the features you will find in the demo include: o A file upload and download counter or filed for each directory entry. AsyDemo automagically increments each field once a transfer is judged successful. o Full macro key support including symbolic carriage return character support. o A high powered and robust Script Language module supporting over FORTY functions and statements including IF/ELSE/ENDIF blocks! This ScriptFile module allows your terminal program to operate from a command file or script file. - This support is comprised of a script file 'compiler'; by producing a symbolic representation of the script file in memory, syntax errors are caught prior to execution and execution time is decreased to a minimum since the entire script file is held in memory - no disk hits after the compilation. This approach also allows you to write support modules that check script files for syntax prior to run time. You need not even include the script file compiler into your program! - Another module 'decompiles' the script file into run time function commands and arguments. This is invoked with a simple CALL statement! Of course, those who purchase a source license will get the source to these modules and a discussion on adding more complex statements and functions to the script language. o An auto-password log on feature: independant of any loaded macro file, Alt-Q sends your password to the remote system. AsyDemo stores a password for each dialing directory entry as well as a comment field and a file transfer count. In spite of these features ASYMODEM is meant primarily as a demonstration vehicle for the AsyLIB functions and for its tutorial aspects of QB4 and async programming. Some of the features it lacks for it to be a full featured TCOMM program include: o A way to edit an existing macro file. This is simply because QB's native INPUT and LINE INPUT are inadequate for such things. o The AsyLIB demo, AsyDemo, supports CR translation to CR or CR/LF for incoming carriage returns, and the Script Language has both incoming AND outgoing translation commands supported, the terminal demo does not got so far as to translate incoming Carriage Returns. That is the terminal package demo does not support all aspects supported by the Script File package. o The dialing directory fully supports fields for such things as a comment, an upload or download count and such, yet there is no way to display these items. o The Redial support is suitable for Hayes compatible modedms at best. o Many of the keyboard I/O occasions crudely use simply BASICA statements like LINE INPUT rather than a professional level text input editor like FED. o The Alt+Key menu functions do not allow a way to suspend a log, although this is fully supported in the Script File language AND demo. There are several occasions of this where we have built in abilities or functions into the script file language not supported in the demo. Much of the logic behind some of the demo program's specifics is explained in ASYNC.DOC supplied upon registration, however there are a few points that inpact directly on the routines: First, a named COMMON block is used to make variables available to other modules (sub programs) within the demo and library. This cuts down on the number of variables that need to be passed explicitly as parameters for various calls, and also allows "automatic" access to these key variables to any sub program that might need it. The block is: COMMON SHARED /TComm/ Bps%, Com$, ComFileNum% and should not be changed for the code to perform correctly. Bps: The current active baud rate. COM$: String representation of the comport in use. IE "COM1" or "COM2" ComFileNum: The basic filenumber assigned to the comport file. This is setup in part for easy expansion and in part for some sub program reasons that no longer exist. However, if these variables are used as global parameters throughout the terminal level code module, any changes made to these is automatically reflected everywhere necessary. In many places, you will note the use of SLEEP. This command is available in QB 4.00(b) and acts as a WHILE inkey$="":WEND loop but with the additional function of terminating in x number of seconds OR if a key is pressed. If your implementation of QB4 does not support SLEEP, replace this with the appropriate WHILE/WEND loop. In many places the code is provided but REMmed out. The initial dialing directory, contains only an entry for the Information Booth set at 2400-N-8-1. Likewise the ASYDEMO.INI file is preset to 2400-N-8-1. You may delete these if you wish to reset the defaults, or use the setup facility to set new ones. The terminal program uses the following external files: ASYAUTO.SCR - Script to execute immediately upon start up (optional) ASYAUTO.MAC - Macro file to load upon start up (optional) ASYDEMO.DIR - Dialing directory ASYDEMO.INI - Terminal defaults ASYXTERN - Used by the external protocols ASY_R?.BAT - External protocol RECV batch file. 1 for each external protocol. ASY_S?.BAT - External protocol SEND batch file. 1 for each external protocol. V. Script File Language As is, the script file language supports over 40 key functions. The Script File Language supports modules to compile and interpret a script file as well as 2 additional routines to read and write a com- piled script to disk are included in both the LIB and source code licenses. Those who purchase a source code license will get complete source to the script file compiler and reader and the ability to add as many additional functions as their desire, ingenuity (and programming ability) allow. Script file commands: ALARM x - Sound the alarm for x seconds. ATIME x - Sets the default number of ALARM cycles. BAUD x - Set the BPS parameter to x CBUFFER - Clears the comport buffer - same as Alt-B (Burp ?) from terminal mode in ASYMODEM CDET - Sets a module level variable indicating the carrier detect state. This allows for easy further expansion beyond 'IF CD'. CLRS - Clear the screen COLOR x - Set the screen colors to th attribute x CLOG - Close the log file CRIN - Set the carriage return IN option (CR or CR/LF) CROUT - Sets the carriage return OUT option (CR or CR/LF) that you may implement in your terminal package. DATABITS x - Set the Databits or WordLen paramter to x. DIAL x - Dials entry x from the fone directory. DELAY x - Pauses x seconds ECHO [ 0|1 ] - Sets the echo status ON (1) or OFF (0) ELSE - Indicates an alternative block of statements to execute in a IF/ELSE/ENDIF block ENDS - Stops the script file, exits to terminal mode ENDIF - Marks the end of an IF...END IF block EXEC y$ - Executes script file represented in y$ HANGUP - Hangs Up the phone IF - The classic block IF/ELSE/ENDIF. In this implementation, the the only subject conditions to the IF statement are 'waitfor' and 'cd' to test the state of the last WAITFOR x$ x or the state of the carrier. LMODE [APPEND | OUTPUT ] - Sets the log file write mode LOCATE x y - Locates the cursor to location x, y (note no comma in the script file syntax). LOGN y$ - Sets the Log file name to that named in y$. MLOAD y$ - Loads the macro file named in y$ MSEND x - Sends entry x from the loaded macro file. OLOG - Opens the log file named in LOGN for write mode specified in LMODE PASSWORD - Sends the password stored for the dialing directory entry you are online with. Equivalent to Alt-Q from the Terminal mode keyboard. PARITY x - Sets the parity variable to x PORT x - Set the active comport to x. PRINT y$ - Prints the String y. See CRXlate and SetCRChar for information on embedded carriage return characters. PREFIX y$ - Sets the dialing prefix (ATDT, ATDP, ATDT15559000 etc) to that specified in y$ PROTOCOL x - Sets the protocol pointer to x. QUIT - Exits the terminal package RECV y$ - Recieves the file indicated by y$ using the protocol set by the PROTOCOL command. RLOG - Resumes logging to a log file previously suspended (SLOG). RSHELL - Remote Shell SEND y$ - Sends file y$ using the protocol indicated by PROTOCOL SETC - Sets Comport and parameters to those indicated by script commands CPORT, BAUD, DATABITS, STOP and PARITY. SLOG - Suspends logging to the log file, until closed (CLOG) or resumed (RLOG). STOPBITS x - Sets stop bits to x TERMINAL - Enter Terminal mode TRANSMIT y$ - Sends the string y$ to the active comport. See CRXlate and SetCRChar for information on embedded carriage return characters. WAITFOR y$ x - Wait for the string x$ for a maximum of x seconds. In addition to performing the WAITFOR act, it sets a module level variable that can later be tested with the IF statement. ; - Remark character: everything after a semi colon is ignored x is any valid integer numeric. Integer EXPRESSIONS such as (Qwerty - Foobar) are NOT supported y$ is any UNQUOTED string LITERAL: WAITFOR foobar 22 ...is legal WAITFOR y$ 22 ...is not legal WAITFOR "foobar" 15 ...is not legal NOTE: The strings arguments to script file statements and functions are _NOT_ to be enclosed in quotes. Example: CORRECT: WAITFOR graphics 35 WRONG: WAITFOR "graphics" 30 ScrCompiler uses the spaces in the line read to parse the arguments and does not need quotes. Further, the TAB character is not supported, the script file handler routines will not parse the line correctly that has embedded TABS: you may want to write a pre-processor to swap out TABS for spaces (or remove them). VI. Routines NOTE: The Demo and the AsyLIB routines make use of a COMMON SHARED block to make a number of parameters available to all routines who might need them or might in the future. The following line of code initiates such a common block: COMMON SHARED /TComm/ Bps%, Com$, ComFileNum% In this manner, these parameters need not be passed to routines but are implicitly available to them. Name: AnsiCol Type: Function Source: BAS Syntax: errc = AnsiCol(Col%, a$) This returns into a$, a string containing ANSI codes that will LOCATE the local and remote cursor to the desired column position passed in Col%. This string must be printed or run thru ANSI for it to work, and naturally ANSI must be loaded. Errc is set (-1) when the column is not valid (not in the range 1 to 80). Example: errc = AnsiCol(4, a$) ' get string for LOCATE 4, via ANSI IF errc = 0 THEN ' col was legitimate CALL AnsiPrint(a$, Arow, Acol) ' locate/print it locally CALL SendString(a$, 0) ' locate/print it on remote END IF Name: AnsiColor Type: Function Source: BAS Syntax: errc = AnsiColor(fg%, bg%, a$) Returns into a$ a string of ANSI codes to set the local and/or remote terminal's colors to those indicated by fg and bg. This allows you to pass it BASIC color codes and let it make an ANSI string from them. Errc is set (-1) if any of the colors is out of range (fg 0 to 31, bg 0 to 7). Example: errc = AnsiColor(14, 0, a$) ' get ANSI color$ for COLOR 14, 0 IF errc = 0 THEN CALL AnsiPrint(a$, Arow, Acol) ' print it locally CALL SendString(a$, 0) ' print it on remote END IF Name: AnsiRow Type: Function Source: BAS Syntax: errc = AnsiRow(Col%, a$) This returns into a$, a string containing ANSI codes that will LOCATE the local and remote cursor to the desired row position passed in Row%. This string must be printed or run thru ANSI for it to work, and naturally ANSI must be loaded. Errc is set (-1) when the column is not valid (not in the range 1 to 80). Example: errc = AnsiRow(4, r$) ' get string for LOCATE 4, via ANSI errc = AnsiCol(1, c$) ans$ = a$ + b$ CALL AnsiPrint(ans$, Arow, Acol) ' locate/print it locally CALL SendString(ans$, 0) ' locate/print it on remote Name: BaudRate Type: Function Source: BAS Syntax: IncomingBaud = BaudRate(Cport) This reads the connected, baud rate from the serial port indicated. While 'smart' modems may automatically adjust to the correct incoming speed when in answer mode, you may well want to change the terminal program's parameters - likewise in a BBS system. This could be done with a call to ReadBaud and then a call to CommPortInit (see the caution under CommPortInit). Example: IncBaud = BaudRate(Cport) ' read the callers baud rate IF IncBaud <> BPS THEN ' Caller BPS = ours? BPS = IncBaud ' nope, make global var theirs CALL InitComPort(CPort, BPS, Parity, Wlen, StopBits) END IF Name: CANAbort Type: SUB Source: BAS Syntax: CALL CANAbort This is a simple routine to send the normal CAN-ABORT sequence to the other side to indicate an aborted or cancelled file transfer. As a CALL, it can be shared by all the file transfer procedures reducing overall code size and make constructing your own protocols a bit easier. Example: IF x$ = CHR$(27) THEN ' local KB input is Escape CALL CANAbort ' tell other side to forget it EXIT SUB ' exit to main code END IF Name: CarrierDetect Type: Function Source: ASM Syntax: cd= CarrierDetect(ComPort%) Returns a value indicating whether DCD (Data Carrier Detect) is true or not for the indicated Comm Port. This works only for COM1 or COM2 as yet, and the ComPort parameter must be an INTEGER. CarrierDetect will return -1 for other than COM1 or 2 and non zero indicating TRUE DCD. Example: IF CarrierDetect(1) = 0 THEN GOTO LostCarrier END IF Name: CCITCRC Type: SUB Source: ASM Syntax: CALL CCITCRC(datastring$, CRCHi%, CRCLo%) Caluculate a hi and lo CRC value for a string. This is similar to CheckSumCRC but is much faster. CheckSumCRC uses the polynominal method to calculate the CRC, whereas CCITCRC uses the table lookup method. This means it is a bit bigger than the polynominal method, but much faster. For optimum performance, AsyLIB uses the combined CRC-CheckSum method for Xmodem which needs to be able to slip from one to another, but the CCIT table look up method for Xmodem1k and all Ymodem variants where the datastring is 1024 (compared to 128 bytes for Xmodem). this assures optimum performance. All paramerters must be integers. Note: You will only need to actually use either CCITCRC or CheckSumCRC if you decide to tinker with your own protocol or one of those in AsyLIB. Example: CALL CCITCRC(x$, CRCHi%, CRCLo%) Name: CheckSumCRC Type: SUB Source: ASM Syntax: CALL CheckSumCRC(DataString$, ChkSum%, CRC, CRCHi, CRCLo) This is a highly useful routine for use in XMODEM file transfer routines. Since it returns BOTH a checksum and a CRC, it is ideally suited for XMODEM routines that should be able to 'sense' which mode, CheckSum or CRC, is active. With both calculations in one routine, code flow based on 'IF CRCMode' type evaluations is considerably easier. Further, while CRCHi and CRCLo are typically used in CRC based protocols, the single byte CRC return allows for use in 'homegrown' type protocols or KERMIT which does support a 1 byte CRC mode. Since this is in ASM, each and every parameter must be of INTEGER type. Name: CommPortInit Type: Function Source: ASM Syntax: errc = CommPortInit(Port%, bps%, parity%, word%, stop%) This is the ASM equivalent to ComPortSetup, performing essentially the same function with one major difference: Once opened via BASIC, the only way to change settings is to CLOSE the file/port and thus break the connection, only to reopen it at the new settings. InitCom allows these settings to be changed on the fly as needed - usually. The viability of this depends in part on the QB 4.00 flavour you are using: we have had no problem using this with QB 4.00 and the (a) version, but strange things seem to happen in 4.00(b). If you use CommPortInit, be sure to thoroughly test your application in both the environment and EXE form! Parameters (all fairly obvious, but all must be integers): Port: Com port (1 or 2) to initialize or set BPS: Baud rate to set COmx to, valid bauds are 19200 to 300 Parity: 0=NONE, 1=EVEN Word: 7 or 8 indicating dtaabits Stop: 1 or 2 indicating Stop Bits Errc: is set to -1 is any parameter is not recognized. Example: nuBPS = 19200 errc = ComPortInit(1, nuBPS, 0, 8, 1) IF errc = 0 THEN BPS = nuBPS ' set global variable PRINT "Baud rate now set to ";BPS END IF Name: CommPortSetup Type: SUB Source: BAS Syntax: CommPortSetUp (CPort%, Parity%, WdLen%, StopBit%, Errc%, BufSiz%) The most important function of this is to act as a control center for initializing the communications paramters, and as such, prevents hard coding practically anything. Secondly, it sets several global parameters (ie COMMON SHARED) required by other modules, which thereby reduces the number of parameters required to be passed. Parameters: CPort: 1 or 2 indicating either COM1 or COM2 Parity: 0=NONE, 1=ODD, 2=EVEN WdLen: 7 or 8 indicating number of data bits StopBit: 1 or 2 indicating the number of stop bits. AsyLIB does not support the 1.5 stop bits mode Errc: Error code is set to 1 on any error(s) BufSiz: Size of the communication buffer to use. Name: CRXlate Type: SUB Source: ASM Syntax: CALL CRXlate(strng$) A support routine to quickly swap out an embedded character to a Carriage return. This is called from the routine that loads a macro file to exchange '{' to carriage returns, and is called from the ScrCompiler sub program to translate CRs in the string arguments to the PRINT and TRANSMIT Script file commands. See also SetCRChar. Example: a$ = "FIRSTNAME{LASTNAME{PASSWORD{" CALL CRXLate(a$) ' The {'s in the string will be converted to carriage returns (ASCII 13). Name: DTRHi Type: SUB Source: ASM Syntax: CALL DTRHi(Cport) This simply tells the modem to hold DTR high until told otherwise (or external modem is turned off, or system rebooted with internal modem). This is especially useful with some minor versions of QB 4.0 to instruct the modem to hold onto DCD while executing a shell operation. This need not be used with QB 4.00(b) for simple shell operations, but you might want to include it in cases where the program shelled TO attempts to alter the port. See DTRLo. Example: ComP = 1 ' using COM1 CALL DTRHi(ComP) ' Set DTR hi on COM1 Name: DTRLo Type: SUB Source: ASM Syntax: CALL DTRLo(Cport) Instructs the modem to drop DTR. This is useful in resetting modems that require 'hard resets' or to reverse a previous call to DTRHi. This is also a little ineffective in QB4.00(b) where the Com Port handling is immensely improved over the other versions, but where QB "hides" the comport address, and seems to 'remember' certain serial port parameters and restores them after a CALL. DTRHi and DTRLo are extremely useful with QB 4.00(a) and QB 4.00 though. See DTRHi Example: ComP = 2 ' using COM2 CALL DTRLo(ComP) ' Set DTR Lo on COM2 Name: FirstF Type: Function Source: ASM Syntax: errc = FirstF(mask$, ret$) This is an ASM support module for low level file access. All the file transfer protocols use low level routines (not BASIC's) for reading and writing files to disk. Further, Ymodem Batch protocol needs a way to find a series of files matching a mask and FirstF and NextF provide this access. All the low level file access routines bear the same name as those in GLIB so that either may be used. Errc returns 18 if there are no matching files (and as such can be used as a File Exist type function), or returns the found filename in ret$. Ret$ MUST be initalized to 12 spaces or else errc is set to -1. Example: fret$ = SPACE$(12) errc = FirstF("*.PAK", fret$) Name: NEXTF Type: Function Source: ASM Syntax: errc = NextF(fret$) Once a FirstF function is executed, NextF can be called to get subsequent matching filenames. When no more files are found, errc is set to 18, if there is not enough room in fret$ for the filename, errc is set to -1. Example: fret$ = SPACE$(14) ' must be at least 12 errc = NextF(fret$) Name: File2Buffr Type: FUNCTION Source: ASM Syntax: errc = File2Buffr(FHandle%, buffer$, BufSiz%) All the file transfer protocols in AsyLIB use buffered file I/O via low level routines to minimize disk access. In the case of a floppy disk system, this will improve performance tremendously, and when compared to a comparable routine that uses BASIC's I/O functions, performance is similarily improved. File2Buffr reads BufSiz% bytes from the disk file represented by Fhandle% into buffer$. Maximum buffer size is 32k, BufSiz should be set the number of bytes to read in, and returns as the number of bytes read. Errc is set to indicate a DOS error such as invalid handle etc. As with the CRC routines, you might never need these unless you decide to try and concoct your own protocol or tinker with one of those in AsyLIB. Example: buf$ = SPACE$(1024) ' set up a 1k Buffer f = FREEFILE ' get a file num from BASIC OPEN "myfile" FOR INPUT AS #f Fhandle = FILEATTR(f, 2) ' get DOS File Handle BSiz = LEN(buf$) ' bytes to read (BSiz = 1024 is ' will work too. errc = File2Buffr(Fhandle%, bufr$, bsiz) ' read 1k into bufr$ Name: Buffr2File Type: Function Source: ASM Syntax: errc = Buffr2File(Fhandle%, bufr$, bytes%) As you can probably guess, this performs the reverse of File2Buffr by writing a buffer to disk. Where File2Buffer would be used (and is!) in SENDING a file, Buffr2File is used in RECEIVE transfers. Example: errc = Buffr2File(Fhandle%, bufr$, BSiz) ' dumps bytes recieved in bufr$ to the file associated with FHandle. Name: KeyReady Type: Function Source: ASM Syntax: KeyReady% This primitive is used internally by some of the subroutines as well as in the main terminal code to determine if a keypress is waiting in the buffer, WITHOUT actually reading and/or removing it from the buffer. Example: IF KeyReady THEN x$ = INKEY$ END IF Name: KBOption Type: Function Source: ASM Syntax: MOpt = KBOption(ky$) As you can see from the demo terminal program, the actual managing of incoming keyboard and com port characters is quite easy, the bulk of a terminal program is going to be invoking all the extended functions such as [Alt-X] or [Alt-U] etc to execute the specific functions. Naturally an examination of an input keyboard character could tell us whether it is a simple character (A, b, C, u etc) or a shifted character such as Ctrl+key or Alt+key. This is however, an ideal job for ASM. The code is not only MUCH smaller but MUCH faster. NOTE! KBOption does not read a key from the buffer or keyboard, but evaluates a key already read! MOpt returns as an integer indicating combination pressed, only Alt+ and key pad/ cursor key character strings return a MOpt code, that is, Ctrl+ keys are ignored. Once MOpt is gotten, a SELECT CASE construct can be executed to perform the desired function(s). KBOption Returns: 0 - Key press not recognized, ie it is not a Alt+ or cursor key. 1 to 26 Alt + corresponding apha key (1 = A, 2 = B etc). 27 - Home 28 - Cursor Up 29 - PgUp 31 - Cursor Left 33 - Cursor Right 35 - End 36 - Cursor Down 37 - Pg Dn 121 to 132 - Alt + the corresponding top row number key: 121 = [Alt-1], 122 = [Alt-2]...131 = [Alt+-], 132 = [Alt+=] Example: IF KeyReady THEN ' is there a key waiting? x$ = INKEY$ ' yes, read it MOpt = KBOption(x$) ' convert to MOpt code IF MOpt THEN ' is is ALT+something? GOSUB MenuItem ' yeah, do what they want ELSE CALL SendChar(x$) ' nope, send the KB input CALL TAnsiPrint(x$, Ar, AC) ' print it locally END IF END IF Name: MPacing Type: SUB Source: ASM Syntax: MPacing(x) Pauses processing for x milliseconds. This is used in the SendString routine when used to transfer via ASCII to control the pace of the transfer and prevent overrunning your own or the recievers buffer. Name: PurgeCommBuffer Type: SUB Source: BAS Syntax: CALL PurgeCommBuffer At times it is desirable to purge the comm buffer such as immediately after an aborted file transfer. Example: CALL SendXmodem1k(filname$, Success%) IF Success = 0 THEN ' aborted CALL PurgeCommBuffer ' purge buffer SLEEP 1 ' wait a sec CALL PurgeCommBuffer ' again END IF Name: RecChar Type: SUB Source: BAS Syntax: CALL RecChar(TimeLimit%, NextChar$, Status%) This is one of the most used sub programs in AsyLIB: when called, it polls both the keyboard and serial port active for a keypress or incoming character. This polling continues for the number of seconds indicated by TimeLimit OR a key is pressed OR a com port character is received. STATUS returns -1, 1 or 2 code indicating: -1 - Time Expired 1 - Key press waiting in buffer (but NOT read) 2 - Char was recieved from serial port In the case of a keyboard or serial port character - ie time has NOT expired, TimeLimit returns with the number of seconds remianing. For this reason, TimeLImit should be passed as a variable not a numeric literal. If a com port character is seen, it is returned in NextChar$. Example: TLimit = 20 CALL RecChar(TLimit, ch$, Status) ' wait 20 secs for input SELECT CASE Status CASE -1 ' time expired! ch$ = "Good Night Sleepy Head" CALL SendString(ch$, 0) ' send to them CALL T0AnsiPrint(ch$, Ar, Ac) ' local echo GOSUB Hangup ' disconnect CASE 1 ' KB key is waiting ch$ = INKEY$ ' get it CALL SendString(ch$,0) ' show them what we typed CALL TAnsiPrit(ch$, Ar, Ac) ' local echo CASE 2 ' they typed something CALL TAnsiPrint(ch$, Ar, Ac) ' local echo END SELECT Name: RecASCII Type: SUB Source: BAS Syntax: CALL RecASCII (fil$, BSMode) Receives incoming data from the active comport and stores it in the indicated file. The BSMode parameter indicates to the routine how to handle incoming backspace characters ( CHR$(8) ), if BSMode = 1, the literal CHR$(8) is not saved to disk but rather deletes the character preceding character, if BSMode = 0 then BackSpaces are stored to the file as literals. If fil$ is not a valid DOS filename, a run time error will occur, your main terminal code should see to this. Pressing Escape from the local keyboard, aborts the transfer. Example: CALL RecASCII("foo.bar", 1) Name: RecSHELL Type: SUB Source: BAS Syntax: CALL RecShell (Fil$, protoID$, CPort%, Success%) This routine extends the availability of protocols far beyond those directly supported in AsyLIB to virtually any well behaved protocol driver such as the popular DSZ, the hot new JMODEM and others like WXModem and even PCKermit. As is, this procedure, which is based on the method used by PCBoard(TM), will allow up to 26 such external protocols. The transfer's success is guaged by the external driver's return code (aka ERRORLEVEL), so if a given driver does not return an ERRORLEVEL in the case of aborted or failed transfers, the success code parameter may not be right. Note also that external drivers that steal interrupts or work too closely with the hardware may have adverse effects on your terminal code upon return. Protocols and drivers of interest that we have toyed with to one extent or another in this manner are (BOTH from the environment AND .EXE's): DSZ - Zmodem DSZ - Xmodem 1k Overthruster (TM) QMXFER - WXmodem PCKermit - KERMIT JMODEM - Jmodem version 1.09 Parameters: Fil$: The file to send protoID$: A one character identifier specifying the external protocol that is to be used. CPort: 0 or 1 specifying the com port to be used by the external driver. Success: 0 or 1 indicating any perceived error code returned by the driver. This method works by executing a batch file named ASY_R?.BAT where ? is the one character identifier specified in protoID$. This batch file passes the rest of the parameters to the driver in the form of batch file arguments: %1 = Com Port (1 / 2) %2 = Baud Rate %3 = Filename If any of these arguments are not needed by the driver of your choice, simply omit them on the command line. Sample BATCH files are provided. NOTE: IF you are using QB 4.00, you may need to set DTR hi prior to the call to RecShell or SendShell so as to hold carrier until the driver program starts up. If so, simply issue a call to DTRHi. If you you do this, you should almost certainly issue a call to DTRLo when you wish to hangup the modem. We have had little, if any, need to do this with QB 4.00(b), however. Example: protoID$ = "J" ' like in JMODEM CALL RecSHELL ("foo.bar", protoID$, success) Name: RecvGen Type: SUB Source: BAS Syntax: CALL RecvGen(fil$, mode%, success%) Since XModem Checksum, Relaxed Xmodem, Xmodem CRC and Xmodem 1K are so similar, this general purpose recieve module will recieve in any of these methods. In making this module 'smarter' than the XModem only or Xmodem1K only modules, it is a little larger and a slightly slower. However, we can envision some situations where this type approach may be desirable. YmodemG and YModem BATCH are not included because economy of code was the objective, and they are considerably less common. The mode parameter indicates to the sub the protocol to recieve with: 1 = Xmodem CheckSum 2 = Xmodem CRC 3 = Relaxed Xmodem 4 = Xmodem 1K Note that since all of these are reciever driven, with the exception of Relaxed XMODEM, you can tell it to start in the Xmodem 1K mode and the module will 'step' down to Xmodem CRC or Checksum as needed. Since the timing is changed on Relaxed Xmodem, this one should be explicitly passed. By passing Xmodem1K as the mode, you might be able to goose the other side into this bigger block mode even if both sides were expecting to send in Xmodem CRC or Checksum mode. Name: RecXmodem Type: SUB Source: BAS Syntax: CALL RecXmodem(fil$, Success%, CharTime%) This implementation of Xmodem supports 3 major variants of the 128 byte block Xmodem file transfer protocol: Xmodem CheckSum Xmodem CRC Relaxed Xmodem The sub program begins by requesting CRC mode since it is slightly more accurate than CheckSum mode. If the sender does not support CRC mode, then it switches to Checksum. This is all pretty standard, but you have additional control by invoking it in Relaxed Mode. Normal character timing conventions dictate a 1 second per character pacing, however, this is sometimes not long enough if you are operating on a packet switching network such as PCPursuit or CompuServe. In this case, simply passing a longer CharTime will put the protocol into Relaxed Xmodem mode. Further, this implementation of Xmodem, when in relaxed mode, will attempt to add yet another second to the pacing when timeouts are encountered on reading a character. Your terminal package could even list Relaxed Xmodem as a separate supported protocol. CRC and CheckSum modes should be passed a CharTime value of 1, and in most cases, Relaxed Xmodem will work with a value of 2 or 3. Note that you CAN attempt to pass a timing of 0, however, contrary to terminal level code, Xmodem throughput is NOT enhanced by this, in fact it can error out rather quickly. Example: IF relaxed THEN Timing = 3 ELSE Timing = 1 END IF CALL RecXmodem(Fil$, Timing) Name: RecXmodem1K Type: SUB Source: BAS Syntax: CALL RecXmodem1k(fil$, Success%) Xmodem1k is often (and mistakenly) referred to as Ymodem. True Ymodem allows for multiple file transfers as implemented in YmodemB, Xmodem1k however, is simply an expanded XModem protocol transferring 1k data blocks rather than 128 byte blocks. Example: CALL RecXmodem1k(fil$, Success) IF Success THEN PRINT "File received!" END IF Name: RecYmodemB Type: SUB Source: BAS Syntax: CALL RecYmodemB(Success) Since the Ymodem BATCH protocol handles the passing of file names betwixt the sender and receiver itself, you need not pass a file name to receive. The Success parameter indicates a 0 for failure on the first file, and otherwise, the number of files received. Note: We tested this against the YMODEM-B implementation in DSZ, since Mr. Forsberg is the author of both. However, we found that we had to take certain liberties with the 'official' treatise on how to implement YModem BATCH: A 1 second delay needed to be added at start up, a second ACK had to be added when acknowledging End Of Session in order to be sure that sender got it. I am not at all sure why these and a few other things were required, possibly it was an isolated glitch in the DSZ we used (since this is a receiver driven protocol, the problem almost certainly lies with either the treatise or DSZ). Note further though, that we got the BEST performance in Ymodem B when setting it up as an external protocol and using the SHELL approach to execute it through DSZ. This is inherent to QB. Name: RecYmodemG Type: SUB Source: BAS Syntax: CALL RecYmodemG(Fil$, Success) As noted in the ASYNC.DOC, you will recall that Ymodem-G is a 'no-protocol' protocol, that is, while data is packet-ized, the protocol does not ACK and NAK each (or ANY!) packet, in fact, if the software percieves an error in the data received (CRC, block or otherwise), the transfer is aborted. Error detection and correction is left up to the modem. These ARQ (Automatic Repeat Request) modems (such as those supporting MNP level ROM based error correcting code) are expected to detect such errors, request a resend and THEN pass it onto the software. When this fails, the protocol must abort the transfer. YmodemG is one of the faster protocols, in our testing this sub program never got less than 238 cps at 2400 bps. Example: CALL RecYmodemG("FooBar.ARC", SuccessCode) IF SuccessCode THEN PRINT "File Transfer successful!" END IF Name: ScrCompiler Type: Function Source: BAS Syntax: errc = ScrCompiler(Fil$, a$) Compiles a script file into a memory image of that file. The basic supplied Script File module supports over 40 functions. The Script handler modules can be easily modified or added to according to your needs. Complete details are in ASYSCRP.DOC available to those who get a source code license. Errc is set to non zero on error. Name: ScrReader Type: SUB Source: BAS Syntax: errc = ScrReader(Scr$) Interprets and excutes a compiled script file. This may be used either as a called sub program or as a GOSUB type sub routine depending on the construction of your program. This returns -1 on end of script. Name: ScrFRead Type: SUB Source: BAS Syntax: CALL ScrFRead(Scr$, Fil$) Reads a compiled script file from a disk file. Script Files can either be compiled at run time or pre compiled and stored to disk. Compiled scripts cannot be edited, but load much more quickly. This is not supplied in the BBS collection of files but is supplied to all those who register. See also: ScrFWrite. Name: ScrFWrite Type: SUB Source: BAS Syntax: CALL Scr2Write(Scr$, Fil$) Once a Script File is compiled, you can avoid having to recompile it each time by storing it to disk in binary form with ScrFWrite and retrieve it with ScrFRead. In so doing, you can reduce code size by not having to link in the Script File compiler module. Should your terminal program require that the script files be precompiled (ie compiled and the read from a file at run time), you could write an ancillary program to compose, compile and check the script file's syntax, but skip the compile step at execution time by reading the compiled string from disk at runtime. This is not supplied in the BBS collection of files but is supplied to all those who register. See also: ScrFRead. Name: SendChar Type: SUB Source: BAS Syntax: CALL SendChar(char$) Sends the specified character string to the active comport. This can be used as an alternative to SendString, if your application does not require the pacing feature. Example: CALL SendChar("Y") Name: SendASCII Type: SUB Source: BAS Syntax: CALL SendASCII (fil$, pacing%) Sends the specified file to the receiver via the active comport. The indicated file name string must be a valid filename and represent a file that already exists. If it does not exist a run time error will occur, your main terminal code should see to this. The pacing parmeter allows you to pace the transfer by delaying a given number of milliseconds after each line is sent. The pacing value should be in multiples of 100 ms. Pressing Escape from the local keyboard, aborts the transfer. Also, SendASCII expands TABS to spaces. Example: CALL SendASCII("foo.bar") Name: SendGen Type: SUB Source: BAS Syntax: CALL SendGen(fil$, mode%, success%) Since XModem Checksum, Relaxed Xmodem, Xmodem CRC and Xmodem 1K are so are so similar, this general purpose send module will transmit in any of these methods. In making this module 'smarter' than the XModem only or Xmodem1K only modules, it is a little larger and a slightly slower. However, we can envision some situations where this type approach may be desirable. YmodemG and YModem BATCH are not included because economy of code was the objective, and they are considerably less common. The mode parameter indicates to the sub the protocol to recieve with: 1 = Xmodem CheckSum 2 = Xmodem CRC 3 = Relaxed Xmodem 4 = Xmodem 1K Name: SendSHELL Type: SUB Source: BAS Syntax: CALL SendShell (Fil$, protoID$, CPort%, Success%) This routine extends the availability of protocols far beyond those directly supported in AsyLIB to virtually any well behaved protocol driver such as the popular Zmodem in DSZ, the hot new JMODEM as well as others like WXModem and even PCKermit. As is, this procedure, which is based on the method used by PCBoard, will allow up to 26 such external protocols. See RecSHELL for other warnings. This method works by executing a batch file named ASY_S?.BAT where ? is the one character identifier specified in protoID$. This batch file passes the rest of the parameters to the driver in the form of batch file arguments: %1 = Com Port (1 / 2) %2 = Baud Rate %3 = Filename If any of these arguments are not needed by the driver of your choice, simply omit them on the command line. Sample BATCH files are provided. NOTE: IF you are using QB 4.00 or QB 4.00(a), you may need to set DTR hi prior to the call to RecShell or SendShell so as to hold carrier until the driver program starts up, if so simply issue a call to DTRHi. IF you do this, you should almost certainly issue a call to DTRLo when you wish to hangup the modem. We have had little, if any, need to do this with QB 4.00(b), however. Example: protoID$ = "J" ' like in JMODEM CALL SendSHELL ("foo.bar", protoID$, 1, success) See also RecSHELL Name: SendStr Type: SUB Source: BAS Syntax: CALL SendStr(send$) Sends the specified string to the active com port WITHOUT a trailing CR/LF pair and without the pacing time parameter of SendString. This allows you to send a prompt then wait, possibly for input, and then erase the string on the remote terminal by sending the appropriate number of backspace characters ( CHR$(8) ). Example: prompt$ = "More ?" CALL SendStr(prompt$) ' send the prompt CALL RecChar(45, ch$, Status) ' wait 45 secs for reply SELECT CASE Status CASE 2 ' COM input ' regardless of Y or N answer, erase the prompt by ' sending enough BS characters CALL SendStr(STRING$(LEN(prompt$), CHR$(8)) .. .. Name: SendString Type: SUB Source: BAS Syntax: CALL SendString(send$, x) Sends the specified string to the active com port and then waits the number of milliseconds. This allows the SendString routine to send both strings and lines from ASCII files (as one might do in an ASCII file transfer). You most likely will never need to add a pacing value, in which case, set 'x' to 0, but it is there if you need it. Example: x$ = INPUT$(10) ' read 10 chars from keyboard CALL SendString(x$, 0) Name: SendXmodem Type: SUB Source: BAS Syntax: CALL SendXmodem(fil$, Success%, CharTime%) This implementation of Xmodem supports 3 major variants of the 128 byte block Xmodem file transfer protocol: Xmodem CheckSum Xmodem CRC Relaxed Xmodem The sub program automatically recognizes Xmodem Checksum and CRC transfer methods, additionally, you can start it in relaxed mode so as to better cope with time sharing systems like PCPursuit and Compuserve. The Timing value CAN be zero, but unlike terminal level, this does not improve throughput - in fact it will likely error out. See SendXmodem for more information. Example: IF relaxed THEN Timing = 3 ELSE Timing = 1 END IF CALL SendXmodem(Fil$, Timing) Name: SendXmodem1k Type: SUB Source: BAS Syntax: CALL SendXmodem1k(fil$, Success%) Xmodem1k is often (and mistakenly) referred to as Ymodem. True Ymodem allows for multiple file transfers as implemented in YmodemB, Xmodem1k however, is simply an expanded XModem protocol transferring 1k data blocks rather than 128 byte blocks. Example: CALL RecXmodem1k(fil$, Success) IF Success THEN PRINT "File received!" END IF Name: SendYmodemB Type: SUB Source: BAS Syntax: CALL SendYmodemB(Success) Since the Ymodem BATCH protocol handles the passing of file names betwixt the sender and receiver itself, you need not pass a file name to receive. The Success parameter indicates a 0 for failure on the first file, and otherwise, the number of files received. Note: See RecYModemB for additional notes on YmodemB Name: SendYmodemG Type: SUB Source: BAS Syntax: CALL SendYmodemG(Fil$, Success) Ymodem-G is a 'no-protocol' protocol, that is, while data is packet-ized, the protocol does not ACK and NAK each packet, in fact, if the software percieves an error in the data received (CRC, block or otherwise), the transfer is aborted. Error detection and correction is left up to the modem. These ARQ (Automatic Repeat Request) modems (such as those supporting MNP level ROM based error correcting code) are expected to detect such errors, request a resend and THEN pass it onto the software. When this fails, the protocol aborts the transfer. Example: CALL SendYmodemG("FooBar.ARC", SuccessCode) IF SuccessCode THEN PRINT "File Transfer successful!" END IF Name: SetBeep Type: SUB Source: ASM Syntax: CALL SetBeep(Freq, Duration) This sets the frequency and duration that TAnsiPrint will use to sound the speaker when it encounters a beep character ( CHR$(7) ). Duration is set in milliseconds. For reference, the normal, obnoxious BEEP is a frequency of 800 and a duration of 250 milliseconds. TAnsiPrint uses a default tone of 500, 50, which you can change with a call to this routine. Once set, the frequency and duration remain in effect (for TAnsiPrint - BEEP remains the same), until a subsequent call to SetBeep is executed. Example: 'Reset TAnsiPrint's default beep to frequency of 1200 and .25 secs CALL SetBeep(1200, 250) Name: SetBline Type: SUB Source: ASM Syntax: CALL SetBline(Brow) Sets the bottom line for TAnsiPrint in scrolling and CLS operations. Normally, the PC CRT scrolls up one line when a character is printed at (25, 79). SetBline allows you to tell TAnsiPrint to do this scrolling at (22, 79), (24, 79) or even (5, 79). In so doing, it leaves the remaining lines alone so that you need not refresh a status line you may be maintaining. The argument for SetBLine is an integer indicating the bottom line of the terminal or I/O portion of the screen. Example: Blin = 23 ' reserve 24 and 25 for status line CALL SetBline(Blin) Name: SetCRChar Type: SUB Source: ASM Syntax: CALL SetCRChar(c$) In reading and storing macro strings into memory, the Carriage Return is represented by the default character "{". The routine CRXlate exchanges all occurrences of a given character (the default is the left curly brace - ASCII 123) in a string to a carriage return (ASCII 13). SetCRChar is used to change the default carriage return representation to whatever character you like. The symbolic character should definitely be printable so that it can be properly stored to disk files, but SetCRChar will accept any legal character. See also CRXLate. Example: CALL SetCRChar("#") ' symbolic CR is now # Name: TAnsiCLS Type: SUB Source: ASM Syntax: CALL TAnsiCLS Clears the screen respecting any status line you may have set up using SetBline and works in tandem with TAnsiPrint by setting the current cursor position to (1, 1), however it does not pass back cursor position pointers, so PRINT statements after a TAnsiCLS and before a subsequent TAnsiPrint should execute a LOCATE 1, 1. Example: CASE 3 ' Alt - C, Clearscreen CALL TAnsiCLS Name: TAnsiPrint Type: SUB Source: ASM Syntax: CALL TAnsiPrint(ansi$, AnsRow%, AnsCol%) This is a specially developed print routine that uses DOS calls to display the output. In so doing, if ANSI.SYS is loaded as a device driver, it is used. TAnsiPrint is further specialized to allow a status line as is normally used in TCOM and BBS applications. This bottom line is fully definable by you - you can reserve 1, 2, 3 or more lines for that status line, and TAnsiPrint will scroll the screen at the bottom of your 'window' rather than line 25 and NOT write over the status line. Additionally, you can set a new tone for the standard (and annoying BEEP)! See SetBline, SetBeep and SetCRIN. TAnsiPrint prints the indicated string at the current cursor location. This routine also passes back the updated cursor pointers so that PRINT statements can be used with continuity. However, since TAnsiPrint handles wrap, backspaces and ANSI color codes (if ANSI is loaded), cursor codes and translates CHR$(12) as a CLS command, there is little advantage to using PRINT. You may notice that little or no plain PRINT statements are used in the MODEM demo program. Example: prompt$ = "What is your first name? " ' assign string CALL TAnsiPrint(prompt$, AnsR, AnsC) ' local display CALL SendStrting(prompt$, 0) ' remote display In a host type system, as with a BBS, it might even make sense to have a dedicated variable for output destined for local and remote display, say e$ and make the 2 above CALLs code in a GOSUB: e$ = "Enter to continue" GOSUB Echo .. .. Echo: CALL TAnsiPrint(prompt$, AnsR, AnsC) CALL SendStrting(prompt$, 0) RETURN Name: UpdStatLine Type: SUB Source: BAS Syntax: CALL UpdStatLine( fg, bg) Note: this is an inline type sub found in the ASYDEMO.BAS module. For those applications such as a BBS system or even an extensive terminal package, it is sometimes advantageous to keep certain information on a status line. UpdStatLine demonstrates one way to do this using a single Fixed length string of 80 characters in length passed as a common variable. The use of this is completely compatible with TAnsiPrint and TAnsiCLS. Name: XferMsg Type: SUB Source: BAS Syntax: CALL XferMsg(Proto%, Fil$, SRFlag%, BlkCnt%, BSiz%, Retry%, ErrT%) Any reputable terminal package provides an ongoing status report of a file transfer in progress. The tools in AsyLIB, also provide for this capability. XferMsg is called from inside each and every transfer protocol procedure (except ASCII) to update the screen report. In the best case, a screen save type routine should save the portion of the screen used by XferMsg, your general purpose library should provide this support. Additional capabilities could easily be added to this such as calulating the total time to send a file, the time remaining in a transfer (or both) can easily be added. The QLB versions of the protocols automatically call this routine, but when you receive the LIB version, you can easily change this by removing it from the LIB and replacing it with a sub that either does your own bidding or disable it by replacing it with an empty sub such as this: SUB XferMsg(Proto%, Fil$, SRFlag%, BlkCnt%, BSiz%, Retry%, ErrT%) STATIC END SUB Of course if you purchase a source code license. you can edit it to your heart's content. Parameters: Bps: Modem speed for time calcs Proto: Protocol Type Identifier 1=X, 2=CRC, 3=Y, 4=A... Filename$: Name of file in transit SRFlag: Sending (# Blocks in File), or Recieving(0) BlockCnt: Current block number in transaction RetryCnt: Current Block Retry Count ErrType: Coded error type seen Name: XmitTextFile Type: Function Source: BAS Syntax: retcode = XmitTextFile(fil$, pcount) This is similar to a SendASCII type transfer except it is tailored to fit the needs as would be required in displaying a text file or bulletin to a remote user. PCount indicates the number of lines to display before the first 'More?' prompt, this would typically be read from a users profile record or be a global variable. After PCount number of lines have been transmitted, the remote user is displayed the following prompt: More? (Y)es, (N)o, (C)ontinuous (Enter = YES) After this 'More?' prompt is sent, the routine waits 30 seconds for the response, if none is forthcoming either from the active comport or the keyboard, the routine exits with a return of -1. If "N" is received, the routine closes the file being sent/displayed and exits to the calling module. In spite of the prompt's suggestion to hit Enter or 'Y', virtually any other key sends another PCount of lines from the file. In responding to any other key, a loop can be removed from the code. Should a "C" be returned, the routine sends out another prompt to inform them that [Ctrl-S] suspends transmissions and [Ctrl-X] aborts. XmitTextFile then begins a continous send mode resonding only to a [Ctrl-X] from the comport or local keyboard to abort the process, or a [Ctrl-S] to pause. Note that due to the way BASIC buffers the comport I/O, up to 5 or so lines may be transmitted before the [Ctrl-S] or [Ctrl-X] is perceived as actted upon. If a [Ctrl-S] is received, the transmission pauses and again waits 30 seconds for a response, if more than that passes, while waiting for a response, the routine exits with an error code of -1. Example: errc = XmitTextFile("BLTN8", 23) ' send a bulletin, in 23 line sets IF errc THEN IF CarrierDetect(ComPort) = 0 THEN GOSUB HangUp END IF END IF * * * * * * * * * * * * * * * * The LIB is all done and ready to go, but it looks like I should have added a parameter for you to set the time to more than 30 secs for slower readers. This will be corrected in a future version.