Simtel MSDOS 1992 June

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

/ Simtel MSDOS 1992 June / SIMTEL_0692.cdr / msdos / rbbs_pc / proedit.arc / RBBSPROT.DOC < prev

Wrap

Text File | 1988-12-04 | 19.6 KB | 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.