ProfitPress Mega CDROM2 Shareware Freeware (MSDOS)(1992)(Eng)

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

/ ProfitPress Mega CDROM2 …eeware (MSDOS)(1992)(Eng) / ProfitPress-MegaCDROM2.B6I / BBS / RBBS_PC / RBBSDOCS.ZIP / RBBSDOCS.20 < prev next >

Wrap

Text File | 1990-11-05 | 20.7 KB | 426 lines

RBBS-PC's STANDARD INTERFACE FOR PROTOCOL DRIVERS 20-1 20. RBBS-PC's STANDARD INTERFACE FOR PROTOCOL DRIVERS ----------------------------------------------------- RBBS-PC includes a flexible interface for implementing file-transfer protocols. A "protocol" for the exchange of files is just a set of cooperative conventions that allow two different computer's software to transfer files between themselves. RBBS-PC supports four "protocols" within its own BASIC source code -- ASCII, Xmodem (checksum), Xmodem (CRC), and 1K-Xmodem. These are totally configurable by the SysOp when setting up RBBS-PC. In addition to these four "protocols" and in order to provide advocates of specific protocols a means of adding their particular flavor of communications protocol to RBBS-PC, a standard interface has been created so that "external" protocols can be installed in RBBS-PC. "External" protocols are simply defined as programs outside of RBBS-PC which perform the file transfer. 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 control of the communications port to the external protocol. RBBS-PC will call the external protocol drivers either via the SHELL command in BASIC or via a .BAT file. 20.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, only internal protocols will be available -- Ascii, Xmodem, XmodemCRC, 1K-Xmodem. 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 protocol 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 Protocol Name -- The FIRST CHARACTER is the letter by which a caller selects the protocol. The prompt for the selection of protocol includes RBBS-PC 17.3A TECHNICAL REFERENCE MANUAL 20-2 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 will normally put each protocol on the same line, separated by a comma, until the line gets too long. The 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. Security Level -- This is the minimum security to be able to use the protocol being described. 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, 1K-X(Y)modem, 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". 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. RBBS-PC's STANDARD INTERFACE FOR PROTOCOL DRIVERS 20-3 Whether A Reliable Connection 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). Whether Batch is supported -- 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. RBBS-PC enters an external protocol only once to do multiple file downloads. RBBS-PC has been tested with such "batch" protocols as Omen Technologies' DSZ Zmodem, Megalink, and Sealink. 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. 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, which stands for "Fake" a success report. This means that all transfers will be regarded as successful. Zmodem (DSZ) used in a multi-tasking DOS environment (where the DOS environment variables are shared) and CLINK are examples of protocols that require this to be set. 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. 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. 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. RBBS-PC 17.3A TECHNICAL REFERENCE MANUAL 20-4 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" when an error has occurred. 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". Template to Use for Downloading -- This is required only for external protocols. It tells RBBS-PC how to invoke a download. See section 20.2. Template to Use for Uploading -- This is required only for external protocols. It tells RBBS-PC how to invoke an upload. 20.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 exist, the protocol will not be made available 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 a work array Macros can store the 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 RBBS-PC's STANDARD INTERFACE FOR PROTOCOL DRIVERS 20-5 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 if 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:\utl\zippy -s [FILE]","c:\utl\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:\utl\zippy -s [FILE]" and invoke the protocol for uploads using the following string: "c:\utl\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. 20.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 20.1, parameter 8. 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. RBBS-PC 17.3A TECHNICAL REFERENCE MANUAL 20-6 The failure indicator MUST BE the first character of any specified 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 20.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 20.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 20.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 20.1) would be written as "4=F=A". The external protocol would then append its own information to the log file. 20.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 all transfers are always successful for protocols handled via 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. RBBS-PC's STANDARD INTERFACE FOR PROTOCOL DRIVERS 20-7 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. It supports XMODEM (checksum), XMODEM (CRC), YMODEM, YMODEMG, and IMODEM. YMODEMG and IMODEM 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, 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. Other protocols tested with RBBS-PC include SuperK, Jmodem and Puma.