synchro.net

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

/ synchro.net / synchro.net.tar / synchro.net / modem.madness / SMMNETML / ES_101D.ZIP / ES.DOC < prev next >

Wrap

Text File | 1992-08-01 | 101.6 KB | 3,242 lines

╦ ■ ╦ ╔═╗ ╔═╗ ╠══╗ ╔══╗ ╔══ ╔══╗ ╗╔═╗ ╦ ╗╔═╗ ╠═╣ ╠═╝ ║ ║ ║ ║ ║ ╚═╗ ║ ║ ╠╝ ║ ╠╝ ║ ║ ╚══ ╚═╝ ╩ ╩ ╚══╝ ══╝ ╠══╝ ╩ ╩ ╩ ╩ ╚═╝ version 1.01 ╩ A dynamic mail transmission system for Advanced Engineering's FrontDoor package and other FidoNet front-end mailers User's Guide (C) 1991, 1992, Compact Solutions. All rights reserved. Software development: B. J. Elliston M. W. Hulskamp Documentation: B. J. Elliston - 1 - Chapter 1 PREFACE 1.1 Introduction Welcome to the state of the art in mail transfers! EchoSprint has been developed to satisfy the needs of the world's many system operators active in amateur mail networks and who use electronic mailers (and specifically, users of Advanced Engineering's FrontDoor package). Many of these operators are obligated to use the transfer protocols which are written into their mailers. This may be satisfactory, but other stand-alone protocols exist which may add reliability, speed and other benefits to your transfers. EchoSprint is a file transfer engine for files and mail using FidoNet compliant mailers and allows a number of useful additional features to be implemented. Using a compatible protocol, this broadens the potential for front-end mailers enormously. Transfers can now be conducted more swiftly, with more reliability and perhaps include chatting capabilities during the session. One known protocol even allows simple games to be played with the remote system during a session! 1.2 Features EchoSprint is designed, like packages such as TosScan, to interface directly with FrontDoor. During early development of EchoSprint, it was envisaged that the package would be targeted at FrontDoor users, but it has since been realised that many other mailers satisfy the fundamental requirements for EchoSprint to operate. Such known mailers are BinkleyTerm, D'Bridge and InterMail. - 2 - Much of EchoSprint's operation can be controlled from the FrontDoor Setup program. A handful of other options must be defined in EchoSprint's own configuration editor, since their nature is not common to FrontDoor. If you do not use FrontDoor, these configuration files will still need to be created. Please see Chapter 10 for further details. EchoSprint is a mailer invoked by the front-end when the system receives an external mail string. The calling system is actually another mailer running EchoSprint in an external event whose behaviour is identical to a mail event. Once EchoSprint is loaded on the answering system, a proprietary "G2U" handshake is initiated. Event behaviour, general system behaviour and mail routing are all extracted from your existing FrontDoor configuration. In other words, human callers and non-G2U mailers will all be treated usually. EchoSprint is completely transparent! EchoSprint has been designed to improve on the functionality of current front-end mailers. The main features are described briefly below: o Support for an unlimited number of external protocols including bidirectional protocols. Use of efficient protocols may aid in reducing large feed systems' phone bills by up to 40% or more. o Full zone, point and AKA support. o An in-built file request engine exists for file requests. The system allows use of a failure message through the use of a template, similar to that used by BinkleyTerm or a FrontDoor style message (optionally adding additional text). In either case, specifications (such as maximum transfer time) are followed from the FrontDoor configuration. o File attaches will be sent, too, but must be created in *.MSG format. EchoSprint does not support the temporary packets created by FrontDoor, but still works fine without them. Using the <Alt-T> keypress on FrontDoor's mailer screen, for example, is generally unusable for creating file attaches anyway, because if the mailer exits prematurely, the temporary file attach is removed. - 3 - o If ARCmail is received during the session, then EchoSprint will exit when complete using the errorlevel prescribed in FrontDoor's Setup program, for running your conference mail processor, such as TosScan or Squish. o Several other error conditions and errorlevels exist, but are dealt with in EchoSprint's Setup program and are definable to suit your batch file and to perform operations based on error conditions similar to FrontDoor. o To make installation even simpler, EchoSprint returns errorlevels identical to FrontDoor's internal errorlevels, in the case of internal errors. 1.3 Using this User's Guide The EchoSprint package is by no means necessarily a simple package to install. Depending on your existing setup and the complexity of your network operation, EchoSprint is potentially a configuration giant. This User's Guide is aimed at reducing the time taken to convert some or all of your network communication. It is laid out in a front-to-back order, which, if you follow systematically, will usually have your new system running in under one hour. Throughout the User's Guide, a number of conventions are established. Information listed in point form is done so using a bullet ("o"). Actions to be conducted with another program (such as FrontDoor's configuration editor), are preceded by a greater than symbol (">"). The User's Guide is written as simply as possible, acknowledging the degree of comprehensiveness required to ensure that configuration is a smooth operation. If you find you get stuck at any particular place throughout this User's Guide, it is highly suggested that you re-read that particular section until you understand what is being said. Only at that stage should you proceed. 1.4 Licence agreement This software is protected by both Australian copyright law and international treaty provisions. You must treat this software just like a book, except that you may copy it onto a computer to - 4 - be used and you may make archival copies of the software for the sole purpose of backing up our software and protecting your investment from loss. By saying "just like a book", Compact Solutions means, for example, that this software may be used by any number of people, and may be freely moved from one computer location to another, so long as there is no possibility of it being used at one location or on one computer while it is being used at another. Just like a book cannot be read by two different people in two different places at the same time, neither can the software be used by two different people in two different places at the same time (unless, of course, Compact Solutions' copyright has being violated). Compact Solutions specifically disclaims all other warranties, expressed or implied, including but not limited to implied warranties of merchantability and fitness for a particular purpose with respect to defects in the diskette and documentation, and the program licence granted herein in particular, and without limiting operation of the program licence with respect to any particular application, use, or purpose. In no event shall Compact Solutions be liable for any loss of profit or any other commercial damage, including but not limited to special, incidental, consequential or other damages. - 5 - Chapter 2 INSTALLATION It is assumed that you are already using the FrontDoor e-mail system by Advanced Engineering. It is possible to run EchoSprint with other mailers, providing the mailer features the concept of "external mail strings", where the mailer will exit upon receipt of a variable string. Other known mailers to work with EchoSprint include BinkleyTerm, D'Bridge and InterMail. If a mailer other than FrontDoor is used, see Chapter 10 for further information before proceeding with Chapter 2 and onwards. Regardless of the mailer being used, you should have an active environment variable named "FD" pointing to your FrontDoor system directory) and within that directory, have the files SETUP.FD, EVENT.FD, ROUTE.FD and possibly some additional *.FD files such as PASSWORD.FD or REQUEST.FD. 2.1 Hardware and software requirements EchoSprint has hardware requirements identical to FrontDoor. In short, if FrontDoor runs on your system, EchoSprint will run also. To be precise, however, EchoSprint requires: o Approximately 75KB of RAM. If EchoSprint runs in the same batch file as FrontDoor, EchoSprint can safely be run under multitaskers without the need to make any modifications to program information files (PIFs), etc. o Approximately 150K of disk space (including online documentation). o A Hayes compatible modem with available DTR line, if you have - 6 - configured FrontDoor to control the state of DTR. o An XT- or AT-type keyboard. o Any IBM compatible graphics adapter. o Monochrome or colour monitor. 2.2 Operating system requirements EchoSprint requires that certain conditions be set within the environment in which it will be operating. They are controlled with the two common operating system files, CONFIG.SYS and AUTOEXEC.BAT. > CONFIG.SYS You should have the following lines in your CONFIG.SYS file: FILES=30 (or higher, if you are running under a multitasker) BUFFERS=30 If you are using a disk cache, such as SMARTdrive or HyperDisk, set BUFFERS to about 5. > AUTOEXEC.BAT The following line should be placed in your AUTOEXEC.BAT file: SET ES=C:\ES C:\ES is the directory where the EchoSprint package will be located on your hard disk. This depends on your configuration, so adjust this depending on where you will place the EchoSprint package. EchoSprint requires that this environment variable ("ES") is set before it will even operate (including the configuration editor), to avoid failure in later execution of the software. - 7 - 2.3 Environment variables After you use the SET command, DOS might display the following message: Out of environment space This message means that the available environment space is insufficient to hold the new variable definition. For information about how to increase the environment space, refer to your DOS manual (and in particular, the command line switches for COMMAND.COM). 2.4 The distribution archive EchoSprint has been provided to you within an archive called ES_101x.EXE. It has been created using ARJ version 2.21 and contains an archive banner. Depending on which "flavour" of version 1.01 you have, the archive may be named: ES_101B.EXE (for closed beta testing) ES_101D.EXE (freely distributable demonstration version) ES_101L.EXE (licenced version for registered users) This User's Guide is aimed at users of all these versions. The additional release notes (contained in READ_ME.ES) provide information relevant only to the various "flavours" of version 1.01. If the archive banner is not present when extracting the files from the archive, then your distribution archive has been modified and should not be used. If this is the case, contact the authors as detailed in Appendix D for an authentic archive. Refer to Appendix F for further information on verifying the authenticity of your installation of EchoSprint. When decompressing the archive, place it in its own empty, temporary directory and extract the files by executing the archive. These files will be kept in this directory until installation is complete. At this stage, copy the archive to a safe directory for backup. You may now delete the archive in the temporary directory - it is no longer required. - 8 - 2.5 Directories EchoSprint needs only one directory in which to store its executable and configuration files. Of course, you may leave a copy of the documentation in that directory also, if you wish. When setting the environment variable in your AUTOEXEC.BAT, you should have decided where your EchoSprint directory will be located. Create any directories and sub-directories as necessary. 2.6 EchoSprint files Now that you have an EchoSprint directory, make it the active directory and copy the files listed below, as required, from the temporary directory where you decompressed the distribution archive. 2.6.1 Executable files ES.EXE is the core of the EchoSprint package. This is the file transfer and mailer system, configuration editor, template verifier, documentation reader and nodelist compiler all-in-one. Naturally, this file is required in the EchoSprint directory. 2.6.2 Documentation files Once it has been printed, you may not wish to keep this document (ES.DOC) online. If you do keep it online, you will be able to quickly reference the User's Guide from within the manual reader. This is a worthwhile venture, especially until you are familiar with the package. The User's Guide file (ES.DOC) is expected to be located in the EchoSprint directory. And, if you so desire, READ_ME.ES (final release information) may also be copied to the EchoSprint directory. The two documentation files mentioned above (ES.DOC and READ_ME.ES) are formatted for printing on DOS compatible printers supporting 8-bit ASCII and 66 line pages. To output these files to a printer, type: COPY ES.DOC PRN or COPY READ_ME.ES PRN (depending on which file you wish to output to the printer). - 9 - 2.6.3 Configuration files If you will be using the programmable file request failure template (similar to that used by BinkleyTerm), copy FREQFAIL.TPL to the EchoSprint directory. You can modify this file to suit your own tastes. See section 3.2.4.3.1 for further details on customisation of this template. EchoSprint stores its only other configuration data in a file called SETUP.ES in the EchoSprint directory. By deleting SETUP.ES, you will force EchoSprint to recreate this file during your next configuration session. In this session, the default settings will be placed in the renewed setup file. 2.7 Protocols EchoSprint does its mail transfers using any number of external protocols of your choice. Naturally, the benefit of this is that other protocols may be used instead of the standard protocols written into your mailer. Such protocols may provide superior transfer speeds, error correction, data encryption - even interactive chatting facilities. EchoSprint has been tested with a number of protocols, however, the most useful seen to date have been BiModem, HS/Link and SuperZmodem. Regardless of the protocol(s) you choose to use, you should install these protocols in a directory and be correctly configured for use with your system. Refer to Chapter 8 for detailed guidelines on how such protocols should be configured for use as a "mailer protocol". Such guidelines are general, however, and can be applied to any protocol which you may care to use. 2.8 Networks and multitasking EchoSprint has been tested exhaustively under DESQview, within OS/2 virtual DOS machines and under Microsoft Windows with pleasing results. Inclusion of EchoSprint into a multitasking system is very simple, since EchoSprint occupies much less RAM than front-ends themselves and behaves in similar ways. EchoSprint also - 10 - timeslices and uses DESQview video buffers if DESQview is detected. Installation of EchoSprint into networks is quite simple - define any paths for both FrontDoor and EchoSprint as one of any remapped public directories, and place EchoSprint's files onto the file server. EchoSprint has been tested under Novell NetWare 3.1. - 11 - Chapter 3 CONFIGURATION 3.1 The configuration editor Now that EchoSprint is correctly installed on your system, it is time to configure the package. Make the EchoSprint directory the active directory and enter ES CONFIGURE. The full-screen configuration editor will be loaded and default values will be created. The main menu of configuration items will appear. 3.1.1 Navigating the configuration editor Configuration items may be selected by moving the highlight bar over the item and pressing <Enter>. Various sub-windows may be opened as a result of this, the items on the sub-window will require selection in a similar manner. In some cases, these sub-windows will contain a number of "buttons", which are shown as a pair of parentheses, with an optional dot between them. When this dot is shown, the corresponding option is selected. Buttons are selected with the space bar. At any time whilst using the configuration editor, the following keys are available: <F1> Keyboard help. This key will show a list of possible hotkeys, available at any position in the configuration editor. <F2> Shell to DOS. Type "EXIT" to return to the configuration editor. <F3> Jump to FrontDoor Setup program. The environment variable - 12 - "FD" will be searched for a path to the FrontDoor setup program, which will be run in a shell. This is useful for making changes on-the-fly and making comparisons. If the FD environment variable does not exist or FDSETUP.EXE does not exist in the directory specified by the variable contents, then an error message will be displayed. The configuration may be saved, when completed, by returning from the current window to the main menu by pressing <Esc> as many times as required to close the open windows. Pressing <Esc> at the main menu will prompt you to save changes. Press <Y> to save changes and exit, <N> to exit and to lose changes, or <Esc> to return to the main menu of the configuration editor. If no apparent changes have been made to the configuration (ie. you were just browsing your configuration), pressing <Esc> will exit the configuration editor immediately, and you will not be prompted to save changes. 3.1.2 File sharing This option can be set to either "Yes" or "No". If you are running EchoSprint on a local area network or under a multitasker, be sure to enable file sharing. Not doing this may result in corruption of various files during use. If EchoSprint is only being used in a single-tasking, stand-alone environment, file sharing may be disabled (ie. set to "No"). 3.1.3 Errorlevels This set of errorlevels are returned to the batch file after EchoSprint exits with a condition; be it success or failure. Be sure your batch file accounts for all possibilities. Several internal errorlevels are issued for internal or fatal errors. These are identical to the internal errorlevels issued by FrontDoor. Refer to the relevant section of the FrontDoor User's Guide for information on these errorlevels. 3.1.3.1 Session success This errorlevel is returned when EchoSprint exits after a successful mail session (but no mail was received). - 13 - 3.1.3.2 Session denial This errorlevel is returned when EchoSprint exits after a call if the remote system refused connection due to event behaviour or a session level denial. 3.1.3.3 Session failure This errorlevel is returned when EchoSprint exits after a mail session if the session was terminated by either Sysop or line noise leading to a loss of carrier. This errorlevel will also be returned if EchoSprint is invoked in answer mode, but no carrier was present. This usually occurs if the calling system disconnected between the exchange of control between FrontDoor and EchoSprint on the answering system. 3.1.3.4 Handshake failure This errorlevel is returned when EchoSprint exits after a call if a handshake could not be completed, due either to an incorrect session level password or line noise. The handshake will be retried for up to 30 seconds. 3.1.3.5 No modem response This errorlevel is returned when EchoSprint exits after attempting to initialise the modem when starting an outbound session. 3.1.4 File requests This setting, either "BinkleyTerm style" or "FrontDoor style" defines how file request failures will be announced. If "BinkleyTerm style" is chosen, then the file FREQFAIL.TPL will be used (if not, you may delete it). When this option is chosen, failures will be returned as a *.RSP file, containing the contents of the template, where any macros will be replaced with the session details. If "FrontDoor style" is chosen, then a failure message similar to FrontDoor's will be sent, with a message file appended, if one is defined in FrontDoor's Setup program. - 14 - 3.1.5 Nodelists EchoSprint uses FidoNet compatible nodelists to contact other systems. These nodelists must be fully FTS-0005 compliant (ie. identical in format to the common FidoNet nodelist). This configuration item consists of ten separate fields. Each field may contain the filename of a nodelist (which must be found in the FrontDoor nodelist directory) to be compiled into the common indexes for EchoSprint to reference. Commented lines (ie. any line beginning with the semicolon character, ";") will be ignored by the compiler. 3.2 FrontDoor configuration As mentioned in the features of EchoSprint, the package is highly integrated with FrontDoor - and in particular, its configuration. It would be quite easy to implement all the FrontDoor configuration items into EchoSprint and its configuration editor, but it just makes setting up the package more difficult in the first instance. For this reason, much of the configuration data EchoSprint needs is extracted from FrontDoor's configuration files. Namely: SETUP.FD, EVENT.FD, ROUTE.FD, and optionally REQUEST.FD, PASSWORD.FD and MODEM.FD. A few simple "rules" must be followed when configuring EchoSprint within FrontDoor's Setup program. All relevant information for EchoSprint's operation is used from FrontDoor's matching components. For example, if you have four network addresses and present all AKAs to remote systems with FrontDoor, EchoSprint will do the same. If your system runs flawlessly using FrontDoor's own transfer engine, then EchoSprint will behave in an identical way. Invoke FDSETUP.EXE (for FrontDoor) by pressing <F4> from EchoSprint's configuration editor (if the FrontDoor configuration editor can be found). Alternatively, enter the FrontDoor system directory and type FDSETUP to load this program. 3.2.1 Configuration requirements EchoSprint assumes the following, in order for it to correctly - 15 - operate: o That the event tag to use in an outbound call is correctly defined and has an accompanying schedule block in ROUTE.FD. o That EchoSprint is in fact loaded by the batch file when the "EchoSprint" external mail string is received. There may be exceptions to this: see section 7.1. 3.2.2 External mail strings For your system to answer inbound G2U mail calls, you must create an external mail string for FrontDoor to detect G2U mailers. > Go to Mailer > External mail In the first available blank line from the top, enter a mail string of "EchoSprint" (be sure to correctly capitalise this) and set an unused errorlevel for your batch file. 3.2.3 Events This section of the EchoSprint installation could easily be the most difficult for many users. Proceed through the following sections slowly to ensure the configuration is done correctly. 3.2.3.1 Event configuration and entry > Go to Manager > Events For each event where you will be polling another G2U capable system, set the event to inactive. > Behaviour > Inactive > Yes As an example, if you poll three systems nightly, but one of them still uses another mailer's internal protocols, you should make a duplicate copy of your poll event and make the duplicate one inactive. Do this by keeping the original event (say, event A) active, for your poll using internal mailer protocols. Check the event behaviour for event A and create an event (called B) for your G2U capable systems. Make the duplicate event inactive. The time when the event is run is unimportant, but the length of the event will be treated - 16 - in the same manner as event A. Be sure that event B is inactive and create an external "X" event, using an unused errorlevel for your batch file. During this external event, EchoSprint will be run, and will be instructed to run event B (the inactive event). The event length of the inactive event will be used to determine how long the external mail event will be run for. 3.2.3.2 Schedule tags/mail routing Once you have an inactive EchoSprint mail event, you should update your mail routing file (ROUTE.FD) so that it will never send any mail via the actual front-end mailer. Continuing on from the above example of two events ("A" using protocols internal and "B" being G2U capable), adjust SCHEDULE A in your ROUTE.FD so that no mail is sent using the front-end mailer to your EchoSprint capable systems and create a new SCHEDULE B to send mail to the EchoSprint capable systems. This will be handled by EchoSprint. Remember that conference mail must be scanned as usual before sending it to the EchoSprint capable node and that crash mail and immediate mail outside EchoSprint events will be sent by your front-end mailer using its own protocols. Within each EchoSprint event schedule, a number of new commands are implemented. Some are in fact FrontDoor routing verbs, but behave in slightly different ways. POLL This verb instructs EchoSprint to poll a given system. The POLL verb must be followed by a single 3-dimensional or 4-dimensional address. For example: POLL 3:620/201 or POLL 58:2600/104.1 A missing point field assumes "point 0" of the given node. The zone field must be complete. Any errors in syntax will cause EchoSprint to exit immediately upon initialisation and place a warning notice in the - 17 - FrontDoor log file. ROUTE-TO This verb instructs EchoSprint to deliver ARCmail and files attaches for nodes listed to the system being polled. This verb can be placed before or after the POLL verb. EchoSprint will, by default, collect mail for all of your AKAs (unless the "Pickup waiting mail" event behaviour is set to "No" in the schedule to be used by EchoSprint. The ROUTE-TO verb is to be followed by a series of addresses (either 3- or 4-dimensional). If line length exceeds 255 characters in ROUTE.FD, additional ROUTE-TO verb lines may be added. Any errors in syntax will cause EchoSprint to exit immediately upon initialisation and place a warning notice in the FrontDoor log file. PROTOCOL This verb specifies a identifying keyword for the protocol you are using in this event. The remote system must have the same keyword listed somewhere in their ROUTE.FD file. Failure to meet this condition will result in a handshake failure. Try to adopt common keywords across your network(s). For example, when using BiModem, use the standardised protocol keyword of "BIMODEM". This keyword is not case sensitive, however. EXECUP This verb specifies the command line to be executed when requiring this protocol to be executed in upload mode. EXECDOWN This verb specifies the command line to be executed when requiring this protocol to be executed in download mode. EXECBOTH If this verb is used, it is assumed that the protocol supports bidirectional file transfers. In that case, this verb specifies the command line to be executed when requiring this protocol to be executed in either upload mode, download mode, or both. LOG This verb specifies the path and filename of the DSZ compatible log file which must be created by the - 18 - external protocol. Failure to specify this verb, or if the protocol does not create a 100% compatible DSZ transfer log file, may result in lost files if calls are disconnected prior to all files being transferred. This log file is removed by EchoSprint every time it is run. There is no need to retain the information from this log, however, since EchoSprint will place all relevant information in the FrontDoor log file. 3.2.3.3 Event behaviour Besides the inactive flag in the event behaviour window of FrontDoor's Setup program, other flags which EchoSprint recognises are: o Exit when mail is received o Allow file requests o Attempt to pickup waiting mail o Allow nodes to pick up waiting mail o Pickup file requests o Hold (don't send) file requests o Prioritise outbound calls It would also be a good idea, but not necessary, to set the "Forced" field of the event behaviour of your external event which calls EchoSprint to "No". This will treat the event identically to standard FrontDoor mail events - it will ignore them if missed. It might also be useful to set Forced to Yes, if the BBS is down for a few hours due to a power failure, over your mail event. In this case, as soon as the machine comes back online, it will poll for you. 3.2.3.4 Global answering event On inbound calls, EchoSprint refers to the event behaviour of the - 19 - currently active FrontDoor event. 3.2.4 File requests EchoSprint's file request engine handles file requests in *.MSG (Opus 1.03) format. Update requests are handled in identical ways to FrontDoor and furthermore, passwords are compared with REQUEST.SYS for password-protected files. FrontDoor's session limits are also adhered to. A new feature has been added to EchoSprint's file request engine. If a file is requested, such as RAFTOOLS.ZIP, sending a file request of RAFTOOLS.ZIP&S, will return only one file from all the directories - the largest file. If duplicates exist, still only one will be sent. Requesting RAFTOOLS.ZIP&D will send one file, also - the one with the most recent date stamp. File requests will only be honoured when time and event behaviour allows it. File requests should be composed in the same way as previously (ie. adding " !password" to password-protected file requests). 3.2.4.1 Alias names Alias file request names will be scanned using the FrontDoor "alias" list (for both secure and unsecured sessions). Be sure FrontDoor has been given an alias list filename and that the file exists, using the format: ALIAS C:\FILENAME.EX1 C:\FILENAME.EXn where ALIAS is the alias name, C:\FILENAME.EX1 the path of the first file to send and C:\FILENAME.EXn is the last file to send. 3.2.4.2 Update requests Update requests are also handled by EchoSprint in an identical fashion to FrontDoor - by checking the date of the existing file on your system and sending an update if required. 3.2.4.3 Requestable directories Similarly with alias names, EchoSprint will refer to the requestable directories list provided to FrontDoor. If a file - 20 - request is placed, all matching files in the listed directories will be sent. The format for the requestable directories list is: \DIR1\ \DIR2\ and so on. Where \DIR1\ and \DIR2\ are directories where file requests may be made from. Like FrontDoor, trailing backslashes in the requestable directories list are optional. 3.2.4.4 Service/server requests Due to the nature of these requests, an external protocol is rarely useful in using service and server requests. It is suggested that these messages be written and sent using the immediate mail sending function of your front-end mailer. 3.2.4.5 File request failures If a file request cannot be satisfied for some reason, such as a missing file or an incorrect password, then a failure message will be included amongst the transferred files. If the configuration has been set to use the FrontDoor style message, then see section 3.2.4.5.2 for further information. If you will be using the BinkleyTerm style template file, see section 3.2.4.5.1. All files requested from your system will be accounted for in your FrontDoor log file. 3.2.4.5.1 BinkleyTerm style (template) The template file, FREQFAIL.TPL, is customisable by yourself to add the details you wish to use in your failure messages that FrontDoor does not offer (BinkleyTerm does). A sample FREQFAIL.TPL is included in the distribution archive. The layout is broken down into several sections or blocks; each - 21 - section relating to a different failure condition (in order from beginning to the end of the template): o Missing file o Password failure o Out of time o Out of kilobytes (allowed per poll) o Too many files o No update required o Baud rate too slow to FREQ o Not allowed to request o No FREQs currently allowed Each block is separated by three dashes, starting from column 1. Here is a more comprehensive look at the template file: ; Missing file --- Sorry, %N, I don't have that file online, sorry. Send me NetMail to %A if you think it is just offline. Thank you. %S ; Password failure --- %F has failed - it requires a correct password before it may be file requested. ; Next block, etc. --- and so on. Spacing with blank lines is accepted and comments may be placed in the template using semi-colons (";") starting in column 1. If these are placed on any other column than 1, - 22 - EchoSprint will assume this is text to be placed in the message. The order of each error condition is vital - be sure your message for systems requesting files without a correct password is second in the template, for example. Once your template has been constructed, you may test its validity using the template checking facility. This is a single pass scanner for testing the correctness of the template's layout. You will be informed of errors, but once the layout is correct, you will be given samples of each to show you how the messages will look. To run this, type ES TEMPLATE at a command prompt. The resulting sample file will be called SAMPLE.RSP, and can be found in the EchoSprint directory. As a tip, be sure to place variables that can be unexpectedly long (such as the remote Sysop's name) as close to column 1 as possible. Trying to centre some variable, such as the remote Sysop's name, will rarely result in pleasing output and may even be wrapped to the next line, looking very ugly indeed. Here is a list of available macros. Insert them into the text using %_, where _ is the macro label (ie. %S for your name). Macro Result ----------------------------------------------------------------- A Your network address (or used alias, such as 58:2600/0). B Established baud rate. C Caller's network address. D Today's date. E Error type (Missing file, etc.) F File(s) which failed. G Calling Sysop's first name. H Calling Sysop's last name. I Minimum baud rate for FREQs. J Maximum number of files allowed per poll. K Maximum file(s) size for FREQs. L Caller's location. M Your location. N Calling Sysop's name. O Caller's system name. P Attempted file password. S Your name. T Time (either AM/PM or military, depending on country). U Maximum time for FREQs. - 23 - V Current version information for EchoSprint. Y The soonest time FREQs will be honoured. Z EchoSprint copyright information. If variables are irrelevant, their contents are blank (for example, if a file was requested without a password, but it failed due to being offline, then %P will continue to yield a blank). 3.2.4.5.2 FrontDoor style (message) The FrontDoor style failure message will send a hard coded failure notice, detailing the files which could not be sent. In addition, if your own failure message is added to the FrontDoor message in FrontDoor's configuration editor, it will be appended to the message. > Mailer > File requests > Message defines the name of the included file. 3.3 Nodelists EchoSprint includes its own nodelist compiler. It expects to find any defined nodelists (via the configuration editor) in the FrontDoor nodelist directory. > Global > Filenames > Nodelist defines the path to the nodelist files. EchoSprint will create its index files in this directory. 3.3.1 Compiling nodelists Once the necessary nodelists are installed in the FrontDoor nodelist directory, all that is further required to completely configure EchoSprint's nodelist support is to run the compiler. To do this, enter the EchoSprint directory and enter ES COMPILE. The compiler will scan the raw nodelist(s) and generate index files as required. The number of nodes compiled and any uncompiled nodelists will be reported in the FrontDoor log file. More detail on the command line parameters for EchoSprint is provided in section 4.2. - 24 - Chapter 4 ECHOSPRINT This chapter, which describes the technicalities to operating EchoSprint, will be most beneficial to users who are very familiar with FidoNet compatible mail software. They should be able to quickly scan this chapter and extract most of the information that they will need. 4.1 The executable The executable program is incredibly small for its task, occupies a very small amount of RAM (for running in memory restricted systems and under multitaskers) and due to its optimisation, runs extremely quickly. As an illustration of this speed, this week's FidoNet nodelist (approximately 1,450KB in size) compiles using the EchoSprint nodelist compiler in nine seconds. To further increase the compactness of this package, the executable file (ES.EXE) has been compressed using PKLite. To avoid the possibility of a file virus attaching itself to EchoSprint, it is possible to set the read-only and/or hidden file attributes to ES.EXE. 4.2 Command line parameters EchoSprint requires command line parameters for any of its operations. These parameters may be in uppercase, lowercase, or any combination of these. o Valid syntax: Poll, pOll, POLL, poll Any of the parameters may optionally be proceeded by a forward slash character ("/"), if this is preferred. - 25 - o Valid syntax: POLL, /POLL Any secondary parameters which have arguments (Event and Password are the only two), must have a colon character (":") separating the parameter and the argument. o Valid syntax: EVENT:A, /PASSWORD:SECRET 4.2.1 Poll This option will invoke EchoSprint in mailer mode to poll a system. The systems to poll and routing is defined in ROUTE.FD for the event to be run, and the behaviour is defined by the inactive event FrontDoor's event manager. This parameter carries with it one optional parameter (Event) and one compulsory parameter (Password). See Section 4.2.6 and Section 4.2.7, respectively, for further details on these secondary parameters. o Example: ES /POLL /EVENT:M /PASSWORD:AARDVARK 4.2.2 Answer This option will invoke EchoSprint in mailer mode, once again, to answer an inbound call. EchoSprint expects a carrier to be present upon loading, which will have a G2U system online, ready to handshake with. The event behaviour will be determined by the event running at the time the front-end answered the call. There are no secondary parameters for Answer. o Example: ES /ANSWER 4.2.3 Configure This option will invoke EchoSprint's configuration editor. There are no secondary parameters for Configure. o Example: ES /CONFIGURE - 26 - 4.2.4 Compile This option will invoke EchoSprint's nodelist compiler. It runs completely unattended, so it may be added to maintenance batch files for compiling new nodelists and so on. The total number of compiled nodes will be added to the log file. There are no secondary parameters for Compile. o Example: ES /COMPILE 4.2.5 Template This option will invoke EchoSprint's template file verifier for FREQFAIL.TPL (used with BinkleyTerm style file request failure messages). The output of this function may be too fast to read, but its actions are logged in the FrontDoor log file. There are no secondary parameters for Template. o Example: ES /TEMPLATE 4.2.6 Password Generally, you will want to configure your front-end to allow exits to EchoSprint upon receipt of the standard "EchoSprint" external mail string. This will allow a majority of systems who have not previously arranged a secured mail feed to connect to your system using a high performance protocol for file requests, crash mail, and so on. If you wish to present a different external mail string to the remote system when polling, use the Password parameter. This is useful for the high security mail or for the remote system to be able to determine which system is calling before loading EchoSprint in answer mode. With this, actions can be taken in the intermediate process to customise operations (for example, routing files or configuration files can be renamed to exchange active files). - 27 - If the Password parameter is not used, the default mail string of "EchoSprint" will be sent to the remote system. This parameter can only be used with the Poll primary parameter. o Example: ES /POLL /EVENT:A /PASSWORD:AARDVARK 4.2.7 Event This compulsory parameter for the Poll option specifies the inactive event information to extract from FrontDoor's configuration files. This includes event behaviour and mail routing information. Valid event tags are a single alphabetic character, except "X" (which is reserved for external events). The global event tag, @, may also be used. The length of the @ event is always one minute. EchoSprint will carry out every poll listed in ROUTE.FD within the @ schedule block before exiting. Note that the @ event cannot be made inactive, so EchoSprint's unique routing verbs may generate curious responses from FrontDoor. If your front-end mailer is not FrontDoor, then of course, this trivial problem will not occur. It is certainly possible to use the @ event, but it is not suggested (nor should it be necessary). This parameter can only be used with the Poll primary parameter. o Example: ES /POLL /EVENT:A 4.2.8 Manual This option will invoke EchoSprint's in-built manual reader. If your User's Guide is kept online in the EchoSprint directory, it can be browsed at any time using this option. The following keys are available within the manual reader: <Up> Scrolls up through the User's Guide by one line. <Down> Scrolls down through the User's Guide by one line. - 28 - <Left> Jumps to the previous page of the User's Guide. <Right> Jumps to the next page of the User's Guide. <PgUp> Jumps to the top of the current page. <PgDn> Jumps to the bottom of the current page. <Home> Jumps to the first page of the User's Guide. <End> Jumps to the final page of the User's Guide. <Esc> Allows exiting from the manual reader. You will be prompted to verify that you wish to exit. Pressing <Y> will exit back to the command prompt. Pressing <N> or <Esc> again will return you to the manual reader. <F1> Jumps to the index of the User's Guide. <F2> Prompts for a page number to go to. This is extremely useful if you have previously jumped to the index and found an item of interest on a given page number. You can press <F2>, enter the page number and very quickly, you are on the page containing the material you wish to read. There are no secondary parameters for Manual. o Example: ES /MANUAL - 29 - Chapter 5 OPERATIONAL OVERVIEW This chapter will briefly describe the workings of EchoSprint through day-to-day operations. Knowing what actually goes on is useful for working out problems much more quickly. 5.1 Handshaking When EchoSprint makes an outbound call to another system, it will dial until the inactive event ends or until it connects. As soon as the machines connect, the password string (usually "EchoSprint") is sent down the line to the remote system). EchoSprint will wait up to 30 seconds for the G2U handshake enquiry to be sent from the remote system before disconnecting. 5.2 Sessions When the handshake begins, the following takes place on each end of the transfer: 5.2.1 Polls The machine making the outbound call then responds to the enquiry with an acknowledgement packet consisting of its system details, a list of waiting outbound files, and a list of file requests, if any. 5.2.2 Inbound sessions If the remote system does not deny access, it will return its system information to the calling system, including a list of waiting outbound files for the caller to collect and a list of file requests if any. Also within this packet is a total size of files which the calling system had just requested. - 30 - This packet will be transmitted, and finally, in the third pass of the handshake, the calling system will return the total size of files which the answering system requested. The protocol to be used will be defined by the calling system, and if the same protocol keyword does not exist in the answering system's ROUTE.FD file as a PROTOCOL entry, the call will be disconnected with a session failure condition. 5.3 File transfers The list of files to be received will be displayed on the mailer screen, followed by an accurate estimate of the session length (in minutes and seconds). If the protocol to be used is bidirectional, the EXECBOTH (from ROUTE.FD) line will be executed simultaneously on both machines. If it is a unidirectional transferring method, the calling system will invoke EXECUP followed by EXECDOWN, and the answering system will invoke EXECDOWN followed by EXECUP. When executing any EXEC command lines from ROUTE.FD, EchoSprint will replace all occurrences of the carat character ("^") with the path to the temporary outbound file list (such as C:\ES\OUTBOUND.ES). This file will be automatically maintained by EchoSprint, so you should not be concerned about systems receiving files from a previous session with another system. The mailer screen will be cleared prior to loading these protocols and will log their exit conditions upon returning to the mailer. 5.4 File requests File requests will be processed during the handshake negotiation and any files which cannot be sent will generate a failure message (whose "flavour" depends on your selection in the EchoSprint configuration editor). These packets (.PKT) or response files (.RSP) will be added to the outbound file list. 5.5 Log file EchoSprint records all its actions in FrontDoor's log file (using the Homrighausen log format). How much of the on-screen logging - 31 - which is actually stored in the log is defined in FrontDoor's configuration editor. EchoSprint carefully uses the correct "action ID" characters for the log file, so that FrontDoor compatible log analysers may b used to analyse EchoSprint mail sessions (ie. "=" defines a modem response string). 5.6 Miscellaneous For EchoSprint to determine which files have been completely transferred during a session, it refers to the log file defined in ROUTE.FD next to the "LOG" verb for the protocol being used. This log file must be fully DSZ compatible, otherwise files may be removed which were not sent due to a failed session (such as line noise). The log file will be processed, logging transfers to the FrontDoor log file (if necessary), and deleting or truncating file attaches as necessary. Whether files are truncated, deleted, or neither is extracted from the file attach message flags. If "KFS" is set, the file will be deleted. If "TFS" is set, the file will be truncated to zero length. Once the DSZ log file has been fully processed, EchoSprint will remove it. As mentioned above, any information in it will be transferred to the FrontDoor log file. It should also be carefully noted that EchoSprint will only send NetMail which is compressed into an ARCmail bundle. If a NetMail file attach message is found which is addressed to the remote system and has text in its message body, the text will not be transferred and the message will be deleted once its attached files have been successfully transferred. Be careful to compress any NetMail into an ARCmail bundle if you wish to transfer it via an EchoSprint session. - 32 - Chapter 6 BATCH FILES For EchoSprint to work effectively, the batch file controlling your front-end must be re-written to handle conditions set by both your mailer and now, EchoSprint. This involves editing your "RUNBBS.BAT" batch file using your favourite text editor. 6.1 Control batch file Load up your editor and load in the RUNBBS.BAT batch file (or the main batch file; you may not necessarily call it RUNBBS.BAT, but we'll refer to it as RUNBBS.BAT). Editing this batch file requires handling new errorlevels passed from the mailer, creating a new label to run the EchoSprint software and finally, within the new label, handling errorlevels which may be passed from EchoSprint upon its exit. 6.1.1 Answering and handshaking After your front-end receives its "EchoSprint" (or otherwise) external mail string, it will exit with the errorlevel we assigned the string in FrontDoor's configuration editor. Let's assume it was 150. Find the section of your batch file where your mailer exits and checking is done for errorlevels for external events, mail being received and so on. It would most likely look something like this if you are using FrontDoor. Most mailers would be controlled in this fashion, however: /* RUNBBS.BAT */ @Echo Off :Loop CD \FD - 33 - FD If Errorlevel 162 Goto Clean If Errorlevel 160 Goto Pack If Errorlevel 100 Goto MailReceived If Errorlevel 10 Goto UserBreak If Errorlevel 1 Goto FatalError Goto Loop :Pack CD \Squish Squish Out Squash Goto Loop :Clean CD \Squish SqPack \Max\Area.Dat Goto Loop :MailReceived CD \Squish Squish In Out Squash Link Goto Loop :UserBreak CD \ Cls Goto Done :FatalError Cls Echo Fatal error occurred. Goto Done :Done /* End of file */ You will need to add, between 162 and 100 (to keep the - 34 - errorlevels in DOS' compulsory descending order) a line: If Errorlevel 150 Goto ES_Inbound Assume the following errorlevels were set in the EchoSprint configuration editor: o Session success 200 o Session denial 201 o Session failure 202 o Handshake failure 203 o No modem response 204 You'll also need to add a label block between the Clean and MailReceived labels: :ES_Inbound CD \ES ES Answer If Errorlevel 204 Goto FatalError If Errorlevel 100 Goto MailReceived If Errorlevel 1 Goto FatalError Goto Loop (Errorlevels 200, 201, 202 and 203 need to loop back to the mailer anyway). This takes care of inbound calls. 6.1.2 Polling To poll using an inactive event schedule, add some more lines after your mailer exits (we'll assume the external event to run EchoSprint sets an errorlevel of 164 and that EchoSprint's internal errorlevels are the same as above (200 through to 204). Add, after the mailer exits, between the line running "FD" and errorlevel 162 (to, again, keep the errorlevels in DOS' - 35 - compulsory descending order): If Errorlevel 164 Goto ES_EventA You'll now need to introduce a label between the Goto Loop line and the Pack label: :ES_EventA CD \ES ES Poll Event:A If Errorlevel 204 Goto FatalError If Errorlevel 100 Goto MailReceived If Errorlevel 1 Goto FatalError Goto Loop (Errorlevels 200, 201, 202 and 203 need to loop back to the mailer anyway). 6.1.3 Handling errorlevels As mentioned previously, EchoSprint sets an errorlevel upon exit, based upon the status of the calls it has answered or made. These are, as also mentioned, defined within the configuration editor and should be trapped by your batch file to take action based on call status. The possible errorlevel states and recommended actions are listed below: o Session success: Return to the mailer. o Session denial: Return to the mailer. o Session failure: Return to the mailer. o Handshake failure: Return to the mailer. o No modem response: Terminate the batch file with a fatal error message. o Mail received: Process mail and return to the mailer. - 36 - 6.1.4 Mail processing EchoSprint will exit with the mail received errorlevel as defined in FrontDoor's configuration file if it detects that a conference mail bundle which has been named following the ARCmail 0.60 naming convention has arrived during the session. The errorlevel will be extracted from the inactive event or, if this is set to 0, the general mail received errorlevel will be set. If FrontDoor has been told to exit upon receipt of NetMail, then EchoSprint will set the mail received errorlevel if it detects that an FTS-0001 compliant NetMail packet has been received. If FrontDoor has been instructed to exit upon receipt of any file, EchoSprint will set the mail received errorlevel if it detects that any file has been received. After EchoSprint has been invoked in either Answer or Poll mode, if any of the above conditions are met (based entirely upon FrontDoor's configuration), EchoSprint will set the mail received errorlevel defined in FrontDoor's configuration. You should trap this errorlevel and from it, run your conference mail processor to import the NetMail packets and/or conference mail bundles that EchoSprint has collected during the session. - 37 - Chapter 7 SECURITY Since EchoSprint uses a proprietary handshake protocol (G2U), it has been refined to become one of the most high security sessions known in FidoNet technology networks. As a brief summary of the security logic used (in case your security is lacking anywhere, resulting in handshake failures): o The name of the remote Sysop must match the name listed for their node in the nodelist. o The name of the remote system must match the system name listed for their node in the nodelist (it is not, however, case sensitive). o All other site details (ie. phone number, location, and mailer flags) must match identically between the remote system's handshake packet and their details from the nodelist on your system. o The address being called must match one of the AKAs presented to the calling system. o Naturally, the presented "password" must match one of the configured external mail strings, or EchoSprint will not even be invoked by the answering mailer. 7.1 Handshake security As mentioned numerously throughout this User's Guide, the external mail strings offer a large amount of elementary security to systems. If, using EchoSprint for its main purpose, you configure your system for secure mail feeds with a number of different systems only, it might be a good idea to not assign the "EchoSprint" mail string and instead decide upon a private one to give to your feeding systems (either as a common password, or as - 38 - one each - if you have the space in your FrontDoor configuration to do so). Be sure, however, that if you are willing to accept polls from unarranged systems who will be attempting to use the "EchoSprint" string, that you define it, also. This is just a "high-level" entrance password - once through that stage of negotiation, the stricter G2U handshake must also be negotiated. - 39 - Chapter 8 TECHNICAL SPECIFICATIONS 8.1 Video operation As stated in the hardware requirements, EchoSprint will run on any IBM compatible display adapter. It does so by detecting the frame of video memory in use (whether it is colour or monochrome) and doing very fast direct memory access to that area of memory. If EchoSprint detects DESQview or a DESQview "simulator" upon initialising, it will instead write all screen output to the allocated DESQview video buffer. 8.2 Memory requirements EchoSprint runs purely in conventional memory. It is so small, that swaps to disk or expanded/extended memory are not required when shelling to other applications. EchoSprint requires approximately 75KB of conventional memory to run. It has been run successfully under DESQview using a memory size of only 88KB (this figure includes a copy of the shell that EchoSprint is run in). Naturally, to allow for the running of external protocols and so on, more RAM must be allocated, but if EchoSprint is running under a much larger mailer, the RAM will already be allocated to do so. With regard to disk space requirements, EchoSprint in its entirety (including the documentation, final release notes, configuration file, template file and the executable) occupies approximately 140KB of disk space. - 40 - The nodelist indexes (created by the EchoSprint nodelist compiler in the FrontDoor nodelist directory) are phenomenally small. For this week's FidoNet nodelist (approximately 1450KB in size), the corresponding index files are: INDEX ES 30 17-07-92 5:04a NETS ES 3468 17-07-92 5:04a ZONES ES 84 17-07-92 5:04a 3 file(s) 3582 bytes So, given the potential for a growing nodelist and the smaller nodelists belonging to alternate networks, the indexes are unlikely to exceed 8KB in the near future. 8.2 G2U handshaking The proprietary "G'day to you!" handshake has been modelled from the EMSI handshake protocol used in common day mail systems. The differences are that it has been optimised to send only vital data in the handshake packets. It has been noticed than for many long haul mail sessions, the majority of the session time is spent in session negotiation. Furthermore, it is a three-way protocol, whereby the list of requested files is sent in the packet. In the third pass of the handshake, the remote returns the total size of those files, so that both ends know exactly how long the session will take at the outset, and which files will be transferred. 8.4 File access EchoSprint locks and shares files as necessary under multitaskers and local area networks. The evaluation version of EchoSprint does not support file sharing (even if it has been chosen in the configuration editor). Normally, however, all files are accessed using file sharing, but does not require SHARE.EXE to be loaded. - 41 - Chapter 9 ALTERNATE MAILERS To users who do not normally use FrontDoor as their front-end, this chapter will be of paramount importance. Since the number of MS-DOS based FidoNet compatible mailers is so large, it has been difficult to obtain information regarding the compatibility of EchoSprint with them. As mentioned above, the following mailers have been tested with EchoSprint: o FrontDoor 2.02/non-commercial o FrontDoor 2.10/commercial o InterMail o D'Bridge 1.30 o BinkleyTerm 2.56wb There are undoubtedly countless other mailers which will work with EchoSprint, on the following provisions: o That you actually obtain FrontDoor 2.01 or greater and install the configuration files. o That, given an "external mail string", your current mailer can exit to its calling batch file with a set errorlevel. o That your current mailer allows DOS errorlevel exits from the mailer through elapsed events. o That your mail processor queues outbound mail using file attach messages. If it does not (and instead builds flow files), a number of utilities can make the conversion(s) for you. - 42 - If these can all be satisfied, then you may use EchoSprint with your current mailer. FrontDoor must be obtained and decompressed into a directory (which you have pointed to using an FD environment variable). If you have not already done so, add the FD environment variable using the same procedure as outlined in section 2.3. Once your FrontDoor files are in this directory, you may safely remove all files except for FD.DOC (which you are likely to need), FDSETUP.EXE (which will be required to configure FrontDoor), ROUTE.FD and FDNODE.CTL. Read through the FrontDoor documentation as you work through the FrontDoor configuration editor. Many of the items may be left on their default values. The configuration items to concentrate on are: o Global o Mailer o Modem o Manager This should only require fifteen or so minutes to complete. The file ROUTE.FD must be edited using your favourite text editor to contain the EchoSprint verbs mentioned in section 3.2.3.2. Finally, the FDNODE.CTL file should also be modified to implement cost control and dialling translations. The format of this text file should be familiar to users of other nodelist compilers such as XlaxNode or SysNL. This file must be placed in the directory specified in the FrontDoor configuration editor as being the nodelist directory. Check which path you have set: > Global > Filenames > Nodelist This will also be the directory where the EchoSprint nodelist indexes will be placed. - 43 - With the above in mind, it should be relatively easy to install FrontDoor for the first time (if you are familiar with network operations, you can install just about any mailer easily). Other mailers which are suspected to be compatible with EchoSprint are: o Dutchie 2.90c o SEAdog o Opus 1.03c or greater o TIMS Any difficulties in integrating any mailer into operation with EchoSprint should be directed to the authors. See Appendix D for further details. If EchoSprint has been successfully installed with your mailer (which is not FrontDoor, BinkleyTerm, InterMail or D'Bridge), please contact the authors so that they may make this information available to the EchoSprint support sites. Please include any information which may prove useful to other users of your front-end mailer. - 44 - Chapter 10 RECOMMENDED ACCOMPANYING SOFTWARE It would be unfair fair to make "recommendations" on software as such, but this chapter will be devoted to illustrating which software packages are successfully being used on the systems maintained by the authors. /* 3:620/262 */ o FrontDoor 2.02/non-commercial o EchoSprint 1.01 o Squish 1.01 o Maximus-CBCS 2.01wb o XRobot 2.40 o FEcho 0.94 /* 3:620/247.5 */ o BinkleyTerm/2 2.56wb o EchoSprint 1.01 o FMail 0.90 o GoldEd 2.40 - 45 - Appendix A FOSSIL drivers EchoSprint has been tested using the two most common FOSSIL drivers available today: Ray Gwinn's X00 and David Nugent's Basic Network Utility (BNU). Both of these drivers have given excellent performance using various low-speed and high-speed modems. As a general rule, if your mailer can do file transfers at an optimum speed using its in-built transfer protocols, you should expect to see similar performance with EchoSprint. The only consideration is that, given the vast number of protocols that can be used in conjunction with EchoSprint, they must be configured correctly themselves, if they use the FOSSIL. Refer to the documentation for any protocols you use for further information. - 46 - Appendix B Example batch files Several batch file examples are provided here to assist in the integration of EchoSprint with your current mailer. Our experience has been limited to FrontDoor and BinkleyTerm, so these examples will be based on those, however other mailers should be very similar in operation (for example, InterMail users will find the FrontDoor batch files very close to correct):s For FrontDoor users: /* RUNFD.BAT */ @Echo Off :Loop CD \FD FD If Errorlevel 164 Goto ES_EventA If Errorlevel 162 Goto Clean If Errorlevel 160 Goto Pack If Errorlevel 150 Goto ES_Inbound If Errorlevel 100 Goto MailReceived If Errorlevel 10 Goto UserBreak If Errorlevel 1 Goto FatalError :ES_EventA CD \ES ES Poll Event:A If Errorlevel 204 Goto FatalError If Errorlevel 100 Goto MailReceived - 47 - If Errorlevel 1 Goto FatalError Goto Loop :Pack CD \Squish Squish Out Squash Goto Loop :ES_Inbound CD \ES ES Answer If Errorlevel 204 Goto FatalError If Errorlevel 100 Goto MailReceived If Errorlevel 1 Goto FatalError Goto Loop :Clean CD \Squish SqPack \Max\Area.Dat Goto Loop :MailReceived CD \Squish Squish In Out Squash Link Goto Loop :UserBreak CD \ Cls Goto Done :FatalError Cls Echo Fatal error occurred. Goto Done - 48 - :Done /* End of file */ For BinkleyTerm users: /* RUNBINK.BAT */ @Echo Off :Loop CD \BT BT Unattended If Errorlevel 255 Goto FatalError If Errorlevel 164 Goto ES_EventA If Errorlevel 162 Goto Clean If Errorlevel 160 Goto Pack If Errorlevel 150 Goto ES_Inbound If Errorlevel 100 Goto MailReceived If Errorlevel 1 Goto UserBreak Goto Loop :ES_EventA CD \ES ES Poll Event:A If Errorlevel 204 Goto FatalError If Errorlevel 100 Goto MailReceived If Errorlevel 1 Goto FatalError Goto Loop :Pack CD \Squish Squish Out Squash Goto Loop :ES_Inbound - 49 - CD \ES ES Answer If Errorlevel 204 Goto FatalError If Errorlevel 100 Goto MailReceived If Errorlevel 1 Goto FatalError Goto Loop :Clean CD \Squish SqPack \Max\Area.Dat Goto Loop :MailReceived CD \Squish Squish In Out Squash Link Goto Loop :UserBreak CD \ Cls Goto Done :FatalError Cls Echo Fatal error occurred. Goto Done :Done /* End of file */ - 50 - Appendix C Evaluation version of EchoSprint An evaluation version of EchoSprint has been distributed world-wide for general evaluation prior to licencing the package. The evaluation version is only inhibited in that neither of the two mailer operations (Poll and Answer) will operate. All of the utility operations will work, the package may be configured in full, and the entire User's Guide is included for your inspection. Please view the file ORDER.FRM in the distribution archive of the evaluation version for details on licencing this product. The evaluation copy has been distributed world-wide as ES_101D.EXE. It is compressed using the ARJ archival utility and is self-extracting. This archive must be distributed in this form - do not compress it into a different archiving format. The actual package title is EchoSprint 1.01/demo. The archive (ES_101D.EXE) is available from the following sources: o Anonymous FTP from SIMTEL-20 and associated mirror sites on the Internet (in the ../fido directory). o File request from 3:620/262@fidonet.org (OCS Lab) as ESDEMO or ES_101D.EXE. This is available 24 hours a day, from 2400 baud to 14,400 baud (V.32bis). o ES_101D.EXE has been hatched into the SDS SOFTDIST file echo and may be available from any SDS collection site. - 51 - Appendix D Product support The authors of EchoSprint may be contacted via FidoNet NetMail and EchoMail. Via NetMail (or e-mail), the authors may be reached at: 3:620/262@fidonet.org (To: Ben Elliston) 3:620/247.5@fidonet.org (To: Mark Hulskamp) tp923021@jarrah.canberra.edu.au (Internet e-mail) Via postal mail: Compact Solutions 180 Drake Brockman Drive Holt ACT 2615 Australia Urgent matters may be directed to 3:620/262 as crash mail, since that node runs as continuous mail. An EchoSprint support conference exists and is read and moderated by both the authors. It originates from OCS Lab (3:620/262), but is gradually becoming available elsewhere. Check with your local network coordinator and regional coordinator regarding its availability. The conference is intended to be international and for Sysop-only access. The EchoMail area tag is "ECHOSPRINT". If the conference is not available locally, it may be obtained somewhere more distant, or if necessary, contact the Sysop of 3:620/262 for details on collecting it from there (up to V.32bis). Provide your node number, a session level password of your choice and the compression method of your choice if you wish to poll for the conference from 3:620/262. - 52 - Appendix E Troubleshooting This appendix lists some of the most frequently asked questions about EchoSprint, and the answers to them. Hopefully it will resolve some of your initial problems before having to turn to the support sites for assistance. Q: In the configuration editor, the shelling keys (<F2> and <F3>) do not work. Why? A: EchoSprint should report "Insufficient memory" in this situation, but often the amount of RAM to load the command interpreter will be available, but not enough to fully load the program (such as COMMAND.COM and FDSETUP.EXE). The command interpreter will quickly flash "Not enough memory". Increase the memory available to EchoSprint and try again. Q: EchoSprint is reporting errors concerning the structures of SETUP.FD and/or SETUP.ES. What is going on? A: EchoSprint safeguards against corrupt configuration files. The structure error will appear when: o By attempting to open a FrontDoor configuration file generated by FrontDoor 2.00 or less (ie. 1.99c). o By attempting to open an EchoSprint configuration file which has been corrupted. Q: When compiling the nodelist, for example, I see "Error opening nodelist". The file exists, but EchoSprint can't open it .. why? A: If you are running under a multitasker, and FrontDoor is running in another task, it will have locks on the nodelist files. The licenced version supports file sharing so that - 53 - this problem may be avoided, but in the evaluation version, FrontDoor must be unloaded before compiling your nodelists. Q: What could possibly cause the "session denial" errorlevel to be issued? A: Although not documented, the FrontDoor routing verb "DENY" will also be respected by EchoSprint. If, during the current event, a system is denied using this verb, EchoSprint will also disallow it to connect, yielding the "session denial" errorlevel. Q: What is meant by the "Uh oh" error message? A: Basically, this means that EchoSprint had to terminate unexpectedly. If EchoSprint could gain access to your FrontDoor log file, it will write the error condition and important information for the authors to the log file. Please report these fatal errors (see Appendix D) to the authors and when doing so, please quote the error number and the address at which the error occurred. Q: What about OS/2? A: EchoSprint should run fine under OS/2. If it gives you some trouble, obtain a copy of version 1.49 of the X00 FOSSIL. Borland International are now beginning to support OS/2, and when Turbo Pascal for OS/2 arrives, we will no doubt code a multithreaded OS/2 version as well. - 54 - Appendix F Package authenticity Quoting figures such as cyclic redundancy checks and file sizes in this freely distributable document is a very poor method for authenticity checking on executable files. Being publicly accessible, it is just too easy for someone to incorporate trojan horses into the executable and tamper with the figures quoted in the documentation such that the package will look authentic. It is suggested that files be scanned using a virus protection utility such as McAfee's ViruScan before use, however, should you be concerned about the authenticity of your package, send a NetMail message to the Sysop of 3:620/247.5 requesting the output of the McAfee Validate utility and file sizes. - 55 - Appendix G Credits and thanks Products mentioned in this User's Guide are trademarks of their holders: ARJ Robert K. Jung BiModem Erik Labs BinkleyTerm Bit Bucket Software BNU David Nugent and Unique Computing D'Bridge Chris Irwin DESQview Quarterdeck Office Systems DSZ Omen Technology Dutchie Henk Wevers FEcho W. K. F. van der Windt FMail Folkert J. Wijnstra FrontDoor Advanced Engineering sarl GoldEd Odinn Sorensen HyperDisk Roger Cross HS/Link Samuel H. Smith InterMail InterZone Software Maximus-CBCS Scott J. Dudley Microsoft Windows Microsoft Corporation MS-DOS Microsoft Corporation Novell NetWare Novell, Inc. Opus Wynn Wagner III OS/2 International Business Machines PKLite PKWare, Inc. SEAdog System Enhancement Associates SMARTdrive Microsoft Corporation Squish Scott J. Dudley SuperZmodem Scott M. Baker TIMS Bit Bucket Software X00 Raymond L. Gwinn XRobot Joaquim H. Homrighausen Thanks must go to Rafy Marootians for his help in beta testing this package. Rafy uses programs the way they weren't designed to be! Many thanks to Jason Hecker for the EchoSprint logo. Even if he did draw it on an Amiga. :-) - 56 - Glossary AKA "Also Known As". When two mailers handshake, they are now able to exchange their additional network addresses and exchange mail for those systems in the same session. ARCmail Refers to the naming convention for files originally defined by Thom Henderson. EchoSprint supports the 0.60 revision of the ARCmail convention which is approved by the FTSC. FOSSIL Fido/Opus/SEAdog Standard Interface Layer. This standardised communications driver allows software to interface with a large range of hardware. To use a hardware item with a FOSSIL driven communications program, the user only requires a FOSSIL which supports that hardware. From then on, all FOSSIL based communications software will access the hardware through the FOSSIL and therefore be compatible with it. FTSC FidoNet Technical Standards Committee. FTP File Transfer Protocol. A means of transferring files between two Unix machines across the world-wide Internet. G2U Compact Solutions' proprietary session level protocol. G2U is a variant of the EMSI handshaking protocol, but improves on its shortcomings. G2U stands for "G'day to you!", as a tribute to our Australian culture. - 57 - Contents Chapter 1 PREFACE . . . . . . . . . . . . . . . . . . . . . . 2 1.1 Introduction . . . . . . . . . . . . . . . . . . . . . 2 1.2 Features . . . . . . . . . . . . . . . . . . . . . . . 2 1.3 Using this User's Guide . . . . . . . . . . . . . . . . 4 1.4 Licence agreement . . . . . . . . . . . . . . . . . . . 4 Chapter 2 INSTALLATION . . . . . . . . . . . . . . . . . . . . 6 2.1 Hardware and software requirements . . . . . . . . . . 6 2.2 Operating system files . . . . . . . . . . . . . . . . 7 2.3 Environment variables . . . . . . . . . . . . . . . . . 8 2.4 The distribution archive . . . . . . . . . . . . . . . 8 2.5 Directories . . . . . . . . . . . . . . . . . . . . . . 9 2.6 EchoSprint files . . . . . . . . . . . . . . . . . . . 9 2.6.1 Executable files . . . . . . . . . . . . . . . . 9 2.6.2 Documentation files . . . . . . . . . . . . . . 9 2.6.3 Configuration files . . . . . . . . . . . . . . 10 2.7 Protocols . . . . . . . . . . . . . . . . . . . . . . 10 2.8 Networks and multitasking . . . . . . . . . . . . . . 10 Chapter 3 CONFIGURATION . . . . . . . . . . . . . . . . . . 12 3.1 The configuration editor . . . . . . . . . . . . . . 12 3.1.1 Navigating the configuration editor . . . . . . 12 3.1.2 File sharing . . . . . . . . . . . . . . . . . . 13 3.1.3 Errorlevels . . . . . . . . . . . . . . . . . . 13 3.1.3.1 Session success . . . . . . . . . . . . . . 13 3.1.3.2 Session denial . . . . . . . . . . . . . . 14 3.1.3.3 Session failure . . . . . . . . . . . . . . 14 3.1.3.4 Handshake failure . . . . . . . . . . . . . 14 3.1.3.5 No modem response . . . . . . . . . . . . . 14 3.1.4 File requests . . . . . . . . . . . . . . . . . 14 3.1.5 Nodelists . . . . . . . . . . . . . . . . . . . 15 3.2 FrontDoor configuration . . . . . . . . . . . . . . . 15 3.2.1 Configuration requirements . . . . . . . . . . . 15 3.2.2 External mail strings . . . . . . . . . . . . . 16 3.2.3 Events . . . . . . . . . . . . . . . . . . . . . 16 3.2.3.1 Event configuration and entry . . . . . . . 16 - i - 3.2.3.2 Schedule tags/mail routing . . . . . . . . 17 3.2.3.3 Event behaviour . . . . . . . . . . . . . . 19 3.2.3.4 Global answering event . . . . . . . . . . 19 3.2.4 File requests . . . . . . . . . . . . . . . . . 20 3.2.4.1 Alias names . . . . . . . . . . . . . . . . 20 3.2.4.2 Update requests . . . . . . . . . . . . . . 20 3.2.4.3 Requestable directories . . . . . . . . . . 20 3.2.4.4 Service/server requests . . . . . . . . . . 21 3.2.4.5 File request failures . . . . . . . . . . . 21 3.2.4.5.1 BinkleyTerm style (template) . . . . . 21 3.2.4.5.2 FrontDoor style (message) . . . . . . 24 3.3 Nodelists . . . . . . . . . . . . . . . . . . . . . . 24 3.3.1 Compiling nodelists . . . . . . . . . . . . . . 24 Chapter 4 ECHOSPRINT . . . . . . . . . . . . . . . . . . . . 25 4.1 The executable . . . . . . . . . . . . . . . . . . . 25 4.2 Command line parameters . . . . . . . . . . . . . . . 25 4.2.1 Poll . . . . . . . . . . . . . . . . . . . . . . 26 4.2.2 Answer . . . . . . . . . . . . . . . . . . . . . 26 4.2.3 Configure . . . . . . . . . . . . . . . . . . . 26 4.2.4 Compile . . . . . . . . . . . . . . . . . . . . 27 4.2.5 Template . . . . . . . . . . . . . . . . . . . . 27 4.2.6 Password . . . . . . . . . . . . . . . . . . . . 27 4.2.7 Event . . . . . . . . . . . . . . . . . . . . . 28 4.2.8 Manual . . . . . . . . . . . . . . . . . . . . . 28 Chapter 5 OPERATIONAL OVERVIEW . . . . . . . . . . . . . . . 30 5.1 Handshaking . . . . . . . . . . . . . . . . . . . . . 30 5.2 Sessions . . . . . . . . . . . . . . . . . . . . . . 30 5.2.1 Polls . . . . . . . . . . . . . . . . . . . . . 30 5.2.2 Inbound sessions . . . . . . . . . . . . . . . . 30 5.3 File transfers . . . . . . . . . . . . . . . . . . . 31 5.4 File requests . . . . . . . . . . . . . . . . . . . . 31 5.5 Log file . . . . . . . . . . . . . . . . . . . . . . 31 5.6 Miscellaneous . . . . . . . . . . . . . . . . . . . . 32 Chapter 6 BATCH FILES . . . . . . . . . . . . . . . . . . . 33 6.1 Control batch file . . . . . . . . . . . . . . . . . 33 6.1.1 Answering and handshaking . . . . . . . . . . . 33 6.1.2 Polling . . . . . . . . . . . . . . . . . . . . 35 6.1.3 Handling errorlevels . . . . . . . . . . . . . . 36 6.1.4 Mail processing . . . . . . . . . . . . . . . . 37 Chapter 7 SECURITY . . . . . . . . . . . . . . . . . . . . . 38 7.1 Handshaking security . . . . . . . . . . . . . . . . 38 - ii - Chapter 8 TECHNICAL SPECIFICATIONS . . . . . . . . . . . . . 40 8.1 Video operation . . . . . . . . . . . . . . . . . . . 40 8.2 Memory requirements . . . . . . . . . . . . . . . . . 40 8.3 G2U handshaking . . . . . . . . . . . . . . . . . . . 41 8.4 File access . . . . . . . . . . . . . . . . . . . . . 41 Chapter 9 ALTERNATE MAILERS . . . . . . . . . . . . . . . . 42 Chapter 10 RECOMMENDED ACCOMPANYING SOFTWARE . . . . . . . . 45 Appendix A FOSSIL drivers . . . . . . . . . . . . . . . . . 46 Appendix B Example batch files . . . . . . . . . . . . . . . 47 Appendix C Evaluation version of EchoSprint . . . . . . . . 51 Appendix D Product support . . . . . . . . . . . . . . . . . 52 Appendix E Troubleshooting . . . . . . . . . . . . . . . . . 53 Appendix F Package authenticity . . . . . . . . . . . . . . 55 Appendix G Credits and thanks . . . . . . . . . . . . . . . 56 Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . 57 - iii -