home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Simtel MSDOS 1992 September
/
Simtel20_Sept92.cdr
/
msdos
/
rbbs_pc
/
proedit.arc
/
RBBSPROT.DOC
< prev
Wrap
Text File
|
1988-12-04
|
20KB
|
408 lines
Extract from RBBS-PC v17.1A Documentation Dealing with External Protocols
21. RBBS-PC's STANDARD INTERFACE FOR PROTOCOL DRIVERS
------------------------------------------------------
Before calling "external" protocol drivers, RBBS-PC will do the following:
1. verify that the file exists if the file is to be downloaded.
2. for uploads, verify that the file name requested is valid.
3. pass the communications port to the vendor's protocol-
handling routine with the file opened and carrier detect on.
RBBS-PC will call the external protocol drivers either via the SHELL
command in BASIC or via a .BAT file.
21.1 Parameters passed to a protocol driver.
----------------------------------------------
RBBS-PC detects the installation of external file transfer protocols via an
optional RBBS-PC system file whose default name is PROTO.DEF. If no such
file exists, all and only internal protocols will be available -- Ascii,
Xmodem, XmodemCRC, Ymodem. This file may be used to rename or delete some
or all of RBBS-PC's internal protocols. If a PROTO.DEF file exists, all of
RBBS-PC's internal protocols must be specified in it as well. Internal
protocols are NOT automatically included when a PROTO.DEF file exists!
The protocol definition file has thirteen (13) parameters passed for each
external protocols defined for RBBS-PC. Each parameter can be on a
separate line of its own or all parameters can be on a single line (
separated by commas). The parameters passed for each protocol specified
are:
Parameter Description
1 Protocol Name
2 Security Level required to use protocol
3 Method to invoke protocol
4 Whether 8 bit connection required
5 Whether "reliable" connection required
6 Whether "batch" mode supported
7 Number of bytes in a block transferred
8 Indicate transfer always successful
9 Factor to estimate file transfer time
10 RBBS-PC "macro" to invoke before protocol
11 Method for checking transfer's success
12 Template to use for downloading
13 Template to use for uploading
* 1 Protocol Name
Protocol Name -- The FIRST CHARACTER is the letter by which a caller
selects the protocol. The prompt for the selection of protocol
includes the protocol name. It is recommended that the second
character be ")" to resemble the rest of the prompts in RBBS-PC, e.g.
"Z)modem". RBBS-PC defaults to putting each protocol on the same line,
separated by a comma, until the line gets too long. Each SYSOP can
control the placement of the line by putting a carriage return line
feed at the end of the protocol name. If this is done, the entire
protocol name must be in parentheses. For example, instead of the
prompt
A)scii,X)modem,C)rcXmodem,Y)modem,N)one
a SYSOP may want the prompt to be
A)scii (text files only)
X)modem checksum
C)rc Xmodem
Y)modem (1K Xmodem)
N - None (cancel)
Then the protocol definition file , PROTO.DEF, should be constructed
using quotes (to include the carriage return/line feed in the first
parameter) as follows:
"A)scii (text files only)
",...
"X)modem checksum
",...
"C)rc Xmodem
",...
"Y)modem (1K Xmodem)
",...
"N - None (cancel)
",...
with the remaining 12 parameters put where "..." occurs.
* 2 Security Level required to use protocol
Security Level -- This is the minimum security to be able to use the
protocol being described.
* 3 Method to invoke protocol
Method to Invoke Protocol -- A protocol can be invoked by one of three
methods:
shell,
door, or
internal (S, D, or I).
If "I" is specified, it must be immediately followed by a letter
specifying what internal protocol to use, where the choices are A, X,
C, Y, or N respectively for Ascii, Xmodem, Xmodem CRC, Ymodem, or None
(cancel transfer). "IC" would mean to use RBBS-PC's internal Xmodem
CRC. If no protocol is specified equivalent to the internal "None",
RBBS-PC will add it. If the letter N is used for a transfer protocol,
another protocol must be specified that is equivalent to "None".
* 4 Whether 8 bit connection required
Whether to Require 8 Bit -- By putting "8" in this parameter, the SYSOP is
specifying that the protocol requires the caller to be able to send or
receive 8 data bits. If 8 data bits is required and the caller is not
at 8 bit, RBBS-PC will prompt the caller to change to 8 bit in order to
use the protocol.
* 5 Whether "reliable" connection required
Whether A Reliable Connections Is Required -- By putting "R" in this
parameter, the SYSOP is specifying that the protocol will not be shown
or made available to the caller unless the connections is reliable
(i.e. such as Microcom's MNP protocol that is built into many modems).
* 6 Whether "batch" mode supported
Whether Support Batch -- By putting "B" in this parameter, the SYSOP is
indicating that "batch" file transfers are allowed with the protocol.
"Batch" means a multi-file download request will be processed together.
The receive function in Qmodem's "batch" Ymodem attempts to write the
file being received to the same letter drive and path name as it is
stored on the sending PC. Because it is unlikely that the PC running
RBBS-PC will have the same disk letters and path names as the callers,
it is recommended that QMODEM's "batch" Ymodem not be used for
receiving files via "batch" Ymodem (use DSZ's instead). RBBS-PC enters
an external protocol only once to do multiple file downloads. RBBS-PC
has been tested with such "batch" protocols as Zmodem's DSZ, Megalink,
and Sealink.
* 7 Number of bytes in a block transferred
Blocksize -- This parameter indicates the number of bytes in each block
transferred. This is only used to inform the caller the number of
blocks to expect when downloading. A zero in this parameters will
cause RBBS-PC to report only the number of bytes to expect. For Xmodem
or XmodemCRC this value would be 128. For Ymodem this value would be
1024.
* 8 Indicate transfer always successful
Indicate Transfers Always Successful -- If there is no way for the protocol
to inform RBBS-PC if a transfer was successful, put a "F" in this
parameter. This means that all transfers will be regarded as
successful.
Zmodem (DSZ) used in a multi-tasking DOS environment (i.e. where there
can only be a single environment) and CLINK are examples of a protocols
that require this to be set.
* 9 Factor to estimate file transfer time
Factor to Estimate File Transfer Time -- This is the decimal number used by
RBBS-PC to estimate the elapse time to download a file. The higher the
number, the faster the protocol and the lower the time estimate.
Standard equivalents in RBBS-PC are:
Ascii ......... 0.92
Xmodem ........ 0.78
XmodemCRC ..... 0.78
Kermit ........ 0.78
Ymodem ........ 0.87
Imodem ........ 0.90
YmodemG ....... 0.95
Windowed xmodem 0.78
If no value is specified, a default of 0.87 will be used.
* 10 RBBS-PC "macro" to invoke before protocol
RBBS-PC "Macro" to Invoke Before Protocol -- This is the RBBS-PC "macro"
(i.e. a series of standard RBBS-PC commands) to invoke before invoking
the protocol. It can be used to display special messages, to delay the
start of the protocol, or to prompt for special information passed to
the protocol.
* 11 Method for checking transfer's success
Method for Checking Transfer's Success -- This is required only for
external protocols. This parameter indicates how RBBS-PC is to detect
a file transfer's failure. The format is "x=y=z" where:
x is which parameter tells whether the transfer was successful,
y is the string which indicates failure, and
z is an optional parameter telling RBBS-PC whether to write out
information needed when DOORing to a protocol in advance of
the file exchange.
For QMXFER.EXE from John Friel and the Forbin Project, this would be
"4=F" - meaning the 4th parameter indicates failure if it begins with
"F".
For Zmodem as implemented in DSZ from Omen Technologies, the
proper choice depends on whether SHELLing or DOORing is used.
For SHELLing, put in "1=E" to indicate that the first parameter
uses "E" to indicate an error has occurred. For DOORing, put in
"4=E=A" to indicate that the fourth parameter uses "E" an error
has occured. The "=A" means that RBBS-PC is to do an advance
write of the filename and protocol used. DSZ then appends its
error report to the log file. To the file "XFER-" plus node #
plus ".DEF" RBBS-PC will write out a line containing
"<filename>,,<protocol letter>". Omitting an "=" causes a default
to "4=F". The file checked is "XFER-" plus the node number plus
the extension "DEF". On node 1 the file checked is "XFER-1.DEF".
* 12 Template to use for downloading
Template to Use for Downloading -- This is required only for external
protocols. It tells RBBS-PC how to invoke a download. See the
following section on discussion of "templates".
* 13 Template to use for uploading
Template to Use for Uploading -- This is required only for external
protocols. It tells RBBS-PC how to invoke an upload.
21.2 Calling external protocols using "templates"
--------------------------------------------------
A "template" is used to inform RBBS-PC how to invoke an external protocol.
The first word of the template must be the file name (including file
extension) of the program to invoke. RBBS-PC will check to make sure that
the file exists. If the file does not exits, the protocol will not be made
available to the caller. If the file does exists, the protocol will be
shown to the caller.
RBBS-PC will dynamically substitute values for pre-defined strings inside a
"template". Each supported string is enclosed in square brackets. The
strings supported include:
[n] where n is a positive integer. Substitutes value in the array
A$, which can best be viewed as a work array. Macros can store
prompted values in specific elements in the array.
[FILE]. Name of the file (FILE.NAME$) to be transferred.
[BAUD]. Baud rate. Speed at which the caller dialed RBBS-PC.
[PARITY]. Parity used by the caller.
[PORT]. DOS device name for the communications port to be used for the
file transfer (COM1,COM2, etc.).
[PORT#] Number of the communications port to be used for the file
transfer (1,2,3, etc.).
[NODE]. Number of the RBBS-PC node invoking the file transfer (1,2,3,
etc.).
[PROTO]. Letter of the protocol for the file transfer.
Everything else in a template will be passed intact. If the external file
transfer is to be invoked via a SHELL, it is recommended that the external
file transfer program be SHELLed to directly. If the external file
transfer is to be invoked via a DOOR, it can be either
1.) DOORed to directly using the same template as for SHELLing, or
2.) DOORed to indirectly via a .BAT file with the command parameters
passed to it by RBBS-PC. For example, a "door" for QMXFER might
have a download template of:
"RBBSQM.BAT [FILE] [PORT] [BAUD] [PROTO]"
and the file RBBSQM.BAT have the following in it:
C:QMXFER.COM -s -f %1 -l %2 -c -b %3 -p %4
DOS substitutes the passed parameters for the variables beginning
with the percent sign. .BAT files are needed in doors if there
are additional programs to run before or after the actual file
transfer.
The following examples should provide some help in understanding how to
invoke external protocols:
Example #1:
Z)ippy,5,S,8,,,,,0.98,,,"c:\proto\zippy -s [FILE]","c:\proto\zippy -r [FILE]"
Can be interpreted to be:
used "Z" as invoking letter,
put "Z)ippy" in the prompt,
the minimum security to use this protocol is 5,
the protocol will be invoked via a SHELL command,
an 8-bit connection is required,
estimate the download time as 0.98 times as fast as normal,
use normal RBBS-PC type of report to check for a successful transfer,
invoke the protocol for downloads using the following string:
"c:\proto\zippy -s [FILE]"
and invoke the protocol for uploads using the following string:
"c:\proto\zmodem -r [FILE]"
where the file name is substituted for "[FILE]" in either case.
Example #2:
X)modem,5,IX,8,,,128,,0.8,,,,
Can be interpreted to be:
used "X" as invoking letter,
put "X)modem" in the prompt,
the minimum security to use this protocol is 5,
the protocol is an internal RBBS-PC protocol,
an 8-bit connection is required, and
estimate the download time as 0.8 times as fast as normal.
21.3 Parameters Returned by a Protocol Driver
----------------------------------------------
All protocol drivers are expected to return information about the file
transfer in a file named XFER-xx.DEF where the value for xx is the node ID
(1 to 36). If the protocol cannot accommodate this minimal requirement, it
can still be used by telling RBBS-PC to indicate file transfers are always
successful -- section 21.1, parameter 9.
The one item of information RBBS-PC requires to be returned from an
external protocol drive is whether or not the file transfer was successful.
The failure indicator MUST BE:
a.) the first character of
b.) any parameter
in the file XFER-xx.DEF. To show that file transfer failures are indicated
by the first parameter and the letter "E" in the file XFER-xx.DEF,
parameter 11 (as described in section 21.1) would be written as "1=E". To
show that file transfer failures are indicated by the fourth parameter and
the letter "F", parameter 11 (as described in section 21.1) would be
written as "4=F".
No other information is required when SHELLing to external file transfer
protocols. However, when DOORing to external file transfer protocols the
log file for the transfer MUST HAVE the file name as the first parameter.
Protocol drivers that do not have the file name as the first parameter can
still be used by telling RBBS-PC to write out three parameters (file name,
an empty parameter, and the letter of the file transfer protocol) before
invoking the external file protocol. This is done by using parameter 11
(as described in section 21.1). As an example, to DOOR to an external file
transfer protocol that indicates a file transfer failure by using the
letter "F" in the fourth parameter, but which does not return the file name
used, parameter 11 (as described in section 21.1) would be written as
"4=F=A". The external protocol would then append its own information to
the log file.
21.4 The Protocol Drivers Tested With RBBS-PC
----------------------------------------------
RBBS-PC has been tested with the following protocol drivers:
CLINK -- From System Enhancement Associates. Supports batch file transfers
but requires that transfers always be assumed successful.
DSZ -- From Omen Technologies. Supports Ymodem, Ymodem Batch, YmodemG, and
Zmodem. YmodemG requires a "reliable" connection. DSZ logs the
results of the file transfers to a file specified in the environment
variable DSZLOG. Therefore, the AUTOEXEC.BAT file for an RBBS-PC that
uses DSZ should specify
"SET DSZLOG=XFER-x.DEF"
where x is the node number. DSZ seems unable to create a log file
whenever a drive or path is specified. If invoking ZMODEM via the DOOR
mechanism, use the "=A" option at the end of the success method check
so that RBBS-PC will append the information to the DSZ log it needs and
DSZ will then append the success report. In a multi-user environment
where a different environment variable for each node can not be
specified (i.e. all nodes must share the same DSZ log file), specify
that a all transfers are always successful for protocols handled via
DSZ. See the discussion of parameter 11 in section 21.1 for further
considerations when using DSZ.
MLINK -- MEGALINK protocol supports batch file transfers but requires that
transfers always be assumed successful.
PC-KERMIT -- from Columbia University. PCKERMIT.EXE is supplied by The
Source as a public service and consists of sliding window KERMIT
protocol. The development of "windowing" within the KERMIT architecture
(i.e. Super KERMIT) was funded by The Source and implemented by Larry
Jordan and Jan van der Eijk.
Columbia University holds the copyright and maintains the Kermit
protocol. Like RBBS-PC, Columbia University allows KERMIT to be passed
along to others and "ask only that profit not be your goal, credit be
given where it is due, and that new material be sent back to us so that
we can maintain a definitive and comprehensive set of KERMIT
implementations".
PCKERMIT.EXE is not a terminal program. It simply implements the
Kermit protocol, including the sliding window extension. It will work
with older "Kermit Classic" implementations as well, via automatic
negotiation between the two Kermit programs. PCKERMIT.EXE runs as a
"one-shot" execution then returns to RBBS-PC. PCKERMIT does not
establish a carrier with a remote system. The connection is
established by RBBS-PC. File transfers must always be assumed
successful.
QMXFER -- is supplied by The Forbin Project as a public service and
supports five different protocols -- XMODEM (checksum), XMODEM
(cyclical redundancy check), YMODEM, YMODEMG, and IMODEM. QMXFER was
implemented by John Friel III, author of QMODEM. YMODEM and YMODEMG are
protocols designed by Chuck Frosberg. IMODEM is a protocol designed by
John Friel. The later two are designed to work when the link between
the two modems is "error free" (i.e. both modems have the MNP protocol
built in)> QMXFER.COM runs as a "one-shot" execution then returns to
RBBS-PC. QMXFER does not establish a carrier with a remote system.
The connection is established by RBBS-PC. File transfer failures are
indicated by an "F" in the fourth parameter of the log file returned to
RBBS-PC.
WXMODEM -- is supplied by The Forbin Project as a public service and
supports the window XMODEM protocol designed by Pete Boswell. Like all
of RBBS-PC's protocol drivers, WXMODEM.COM runs as a "one-shot"
execution then returns to RBBS-PC. WXMODEM does not establish a
carrier with a remote system. The connection is established by RBBS-
PC. File transfer failures are indicated by an "F" in the fourth
parameter of the log file returned to RBBS-PC.