home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Simtel MSDOS - Coast to Coast
/
simteldosarchivecoasttocoast2.iso
/
qbasic
/
asylib11.zip
/
ASYLIB.DOC
< prev
next >
Wrap
Text File
|
1988-10-30
|
69KB
|
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.