The World of Computer Software

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

/ The World of Computer Software / World_Of_Computer_Software-02-387-Vol-3of3.iso / c / cn311-sw.zip / CIRCUIT.DOC < prev next >

Wrap

Text File | 1992-05-28 | 117KB | 2,124 lines

Circuit Net Version 3.11 The Best Electronic - Net-Mail System For the Spitfire Bulletin Board System Version 3.11 T A B L E O F C O N T E N T S ------------------------------------------------------------------------ TABLE OF CONTENTS . . . . . . . . . . . . . . . . . . . . . . 2 CONFIGURATION . . . . . . . . . . . . . . . . . . . . . . . . 4 System Requirements . . . . . . . . . . . . . . . . . . . . 4 Setting Up Made easy . . . . . . . . . . . . . . . . . . . . 4 Configuration . . . . . . . . . . . . . . . . . . . . . . 4 Batch files . . . . . . . . . . . . . . . . . . . . . . . 6 Starting from scratch . . . . . . . . . . . . . . . . . . . 7 First things first . . . . . . . . . . . . . . . . . . . . 7 Configuration . . . . . . . . . . . . . . . . . . . . . . 8 Batch files . . . . . . . . . . . . . . . . . . . . . . . 11 Changing from node to host . . . . . . . . . . . . . . . . 14 Configuration . . . . . . . . . . . . . . . . . . . . . . 14 Batch files . . . . . . . . . . . . . . . . . . . . . . . 15 SYSTEM OPERATIONS . . . . . . . . . . . . . . . . . . . . . . 19 The Network . . . . . . . . . . . . . . . . . . . . . . . . 19 Processing Mail . . . . . . . . . . . . . . . . . . . . . . 19 Batch files . . . . . . . . . . . . . . . . . . . . . . . . 20 Mail transfers . . . . . . . . . . . . . . . . . . . . . . . 20 Communications programs . . . . . . . . . . . . . . . . . . 21 FILE EXPLANATIONS . . . . . . . . . . . . . . . . . . . . . . 22 Directories . . . . . . . . . . . . . . . . . . . . . . . . 22 CircuitNET directories . . . . . . . . . . . . . . . . . . 22 Mail Directory . . . . . . . . . . . . . . . . . . . . . . 22 Work Directory . . . . . . . . . . . . . . . . . . . . . . 22 System Directory . . . . . . . . . . . . . . . . . . . . . 22 SpitFire Directories . . . . . . . . . . . . . . . . . . . 22 System Directory . . . . . . . . . . . . . . . . . . . . . 23 Work Directory . . . . . . . . . . . . . . . . . . . . . . 23 Message directory . . . . . . . . . . . . . . . . . . . . 23 Work Files . . . . . . . . . . . . . . . . . . . . . . . . . 24 Mail Packets . . . . . . . . . . . . . . . . . . . . . . . . 24 Dossier Files . . . . . . . . . . . . . . . . . . . . . . . 25 CONFIG.EXE . . . . . . . . . . . . . . . . . . . . . . . . . 26 NODES File . . . . . . . . . . . . . . . . . . . . . . . . . 33 Packet compression . . . . . . . . . . . . . . . . . . . . . 33 PRIMER.EXE . . . . . . . . . . . . . . . . . . . . . . . . . 34 EXTRACT.EXE . . . . . . . . . . . . . . . . . . . . . . . . 34 IMPORT.EXE . . . . . . . . . . . . . . . . . . . . . . . . . 35 MAILCALL.EXE . . . . . . . . . . . . . . . . . . . . . . . . 35 APPENDIX A . . . . . . . . . . . . . . . . . . . . . . . . . 36 LICENSE AGREEMENTS . . . . . . . . . . . . . . . . . . . . . 36 STANDARD DISCLAIMER . . . . . . . . . . . . . . . . . . . . . 38 COPYRIGHT NOTICES . . . . . . . . . . . . . . . . . . . . . . 39 THE ANATOMY OF A MESSAGE . . . . . . . . . . . . . . . . . . 40 SpitFire Messages . . . . . . . . . . . . . . . . . . . . . 40 Circuit Net Messages . . . . . . . . . . . . . . . . . . . 40 APPENDIX B . . . . . . . . . . . . . . . . . . . . . . . . . 44 BASIC CONCEPTS . . . . . . . . . . . . . . . . . . . . . . . 44 APPENDIX C . . . . . . . . . . . . . . . . . . . . . . . . . 46 Source Code and Record Structures . . . . . . . . . . . . . 46 APPENDIX D . . . . . . . . . . . . . . . . . . . . . . . . . 47 Circuit Net Revision history . . . . . . . . . . . . . . . . 47 APPENDIX E . . . . . . . . . . . . . . . . . . . . . . . . . 48 APPENDIX F . . . . . . . . . . . . . . . . . . . . . . . . . 53 REGISTRATION INFORMATION . . . . . . . . . . . . . . . . . . 54 Circuit Net Upgrades . . . . . . . . . . . . . . . . . . . . 55 Registration Form . . . . . . . . . . . . . . . . . . . . . 56 END OF DOCUMENT . . . . . . . . . . . . . . . . . . . . . . . 57 CONFIGURATION Configuring CircuitNET v3.11 has been made as simple as possible. CONFIG.EXE will allow you to setup not only CircuitNET files, but also make any necessary changes to the configuration of your Spitfire setup. System Requirements In addition to the obvious requirement of having an MSDOS or Os/2 v2.0+ based computer and a modem, you must also have Spitfire BBS software version 3.x, and some free space on your hard drive. The amount of free space depends upon the message traffic in the network you will be participating in. 10 Meg of free disk space should be more than sufficient to start with. As you get familiar with the volume of message traffic, the disk space requirements for your particular situation may turn out to be more or less than initially allocated. Setting Up Made easy: **** IMPORTANT NOTE ***** The following sections are divided into two areas that contain instructions for specific situations. The instructions are written in checklist form and should be folloId step by step. ********************** Step one: Choose the ONE of the following sections that applies to your situation, and follow the instructions step by step. *** IMPORTANT NOTE *** SEEDING of conferences is NOT NECESSARY, and only clutters the network with meaningless messages. CONFIG.EXE will seed any conferences created with non-net-mail messages. ********************** Starting from scratch This section is for those setting up CircuitNET for the First time. If you are setting up a second CircuitNET based Network, refer to the section on multiple copies first. First things first **** IMPORTANT NOTE *** CircuitNET Software is intended for use with an established network. The BBS from which you obtained the original information should be able to provide you with the information you will need to properly install the software. If the BBS that provided you with the software cannot help you, then contact any node of the network you wish to participate in for the name of that network's secretary, and contact the network secretary to get assigned to a host whose job it will be to provide you with the necessary information. If you intend to start a new network, then contact Dave Stahl at the address or number given in the registration information appendix. ********************** Before setting up CircuitNET Software, you will need the following information and files from your host: 1) A Node Id. This is a 1 to 8 Alpha-Numeric designation by which your BBS will be identified to the software, and to the network. 2) HOST Node Id. You will need this to tell the software what to name your outgoing mail packets. 3) A current list of conferences available and/or required for you to carry. 4) A copy of the Network Charter, Bylaws, or Rules for the network you are joining. 5) Instructions on how and when to make your mail transfers. In most cases, this will include a special logon account for your BBS to use when calling for mail. 6) Sample scripts for unattended transfers. Or the information required for building a suitable script. (Some sample scripts are included in the CircuitNET distribution packet, but I make no guarantee as to their suitability for any specific host.) Configuration Now that you have the information you need from your host, you are ready to start the installation. You may now turn the page and begin. 1) Using DOS or your favorite disk management utility, create a directory named CIRCUIT. Normally this would be a sub- directory of your Spitfire System directory, but it need not be. If you plan to dedicate a drive to CircuitNET operations, you can use the root directory as your CIRCUIT directory. (If you choose a directory that is not a sub- directory of your Spitfire System Directory, you will be prompted for the path to an SFNODES.DAT file.) 2) Unzip *.EXE from your CircuitNET distribution file into your CIRCUIT directory. If you have not already done so to unzip the files, make your CIRCUIT directory the current DOS directory. 3) Enter CONFIG or CONFIG COLOR to invoke the CircuitNET Configuration Utility. You will be presented with a series of questions before you reach the main menu, and will be told that several directories Ire not found. You either need to tell the program to (M)ake them, or (R)e-enter the name of an existing directory. The default names will identify the purpose of the directory that could not be found. At a minimum, the Circuit\Work, and Circuit\Mail directories should need to be created. (Note: Config cannot (M)ake two directories at once. If a two deep directory is required to be created, you will have to (M)ake only the first at this point, and change the path later in the configuration process.) 3a) Are you a HOST Node (Y/N) N Press Enter to accept the Default of NO. (You should not be in this section if you are a host node. If you are one of those rare cases of a a node joining the net and hosting another new node, then you have my sympathy, and should ansIr Yes, and then skip the CONFIG portion of "Converting from a node to a host.) 3b) Do you want Primer to mark old messages for deletion? Y Press return to accept the default of Yes. This will cause Primer to check for messages older than the old message value configured for each conference as it searches for Net-Mail messages to send. If any are found, they will be explicitly marked as deleted, just as if you had deleted them from within Spitfire, so that the next purge of the message base will purge them. AnsIring No to this prompt will cause Primer to ignore old messages, and only consider the net-mail status as it scans each message conference. 3c) Keep History for how many MSG/Conf (512..2048) 1024 Press enter for the default history size of 1024. You will be able to change this value later if you develop problems with duplicates or incomplete threading, or have consistent out of memory problems with IMPORT. Read the section on system operation for details on when it should be changed, and what effects changing it will have. 3d) Enter BBS Phone number This entry is used to display your phone number in the tagline of messages originating on your BBS. (It is prefixed by the word 'Phone: ' when the tagline is built.) 3e) Enter BBS Name This entry is also used to build the taglines for messages originating from your BBS. It is intended to provide the network users with some idea of where in the world each message came from. (Consult the network rules provided by your host to see if the network you are joining has some rule concerning the information to be put in this field.) 3f) (REGISTERED COPIES ONLY) Enter Your Location or Motto This is also used to build the tagline, but is only displayed in registered versions. The shareware version uses this field to identify unregistered nodes. 4) You should now be presented with the Main Menu for CONFIG. Select (M) to configure the message conferences. This will link the names from the Conference list provided by your host with specific Spitfire conferences. All of the information displayed, save the conference codename, is taken from your SpitFire SFMCONF.DAT, and will Update Spitfire's configuration when you (Q)uit this menu and select (Y)es when asked to save the changes. The Conference Codename field will be written to a file named CNCONFS.CFG in Your CIRCUIT Directory. When the conferences are saved, all conferences are automatically seeded with a non-net-mail message, and the SFMSGxx.LMR files are updated to SpitFire 3.2 standards. (Spitfire 3.1 has no problems with this.) 4a) You are presented with the display for Conference Number 1 of nn, where 'nn' is the total number of conferences configured. Using the '+' and '-' keys you can step through the conferences and set those that will be assigned network codenames to "Net-Mail conference = TRUE". As you change the net-mail status to TRUE, select (C)odename and enter the network conference name that is to be associated with the conference. All of the fields, EXCEPT the Codename field are explained in the Spitfire documentation. All of the fields are covered in the section on CONFIG.EXE also. Conference codenames are explained in detail in the System Operations section under "the Network". 4b) ADDING Conferences: When you have exhausted the conferences which Ire originally configured in SpitFire, you can add more as required, up Spitfire's maximum of 255. Conferences are always added as the LAST conference. The new conference is automatically identified as a net-mail conference, and needs only a CodeName to be completely configured as a network conference. 4c) DELETING Conferences: When you select (D)elete a conference, the LAST conference will be displayed, and you will be asked if you wish to delete it. CONFIG will only delete the last conference, and it DOES NOT delete the SFMSGxx.* Files associated with the conference being deleted. Deletion of the files must be done at the DOS level. 5) Select (Q)uit when you have configured the conferences you wish to echo with the network, and hit enter to save the changes to BOTH Spitfire and CNCONFS.CFG. *** MULTIPLE NODES TAKE NOTE *** The SFMCONF.DAT file is only updated for the node which CircuitNET uses for finding the Spitfire information it needs. If you have multiple nodes that share a message directory, you will need to copy the modified SFMCONF.DAT to the other nodes if you wish them to have access to any added conferences, and any changed descriptions. ******************************** AT this point, CircuitNET and SpitFire are configured for echoing messages to and from the network manually. Meaning that you can now use Primer, Extract and Import from the DOS command line to build and process mail packets. A rather cumbersome and usually erratic means of day to day net-mailing. So you need to automate the process through batch files. Batch files In order to automate your mail transfer, you will need to configure a scheduled event to invoke Primer and Extract, invoke a communications program to exchange mail packets with your host, and then invoke Import. The sample batch file NODEVENT.BAT included in the documentation package contains all of the required commands to automate your mail transfers. Your host should be able to tell you what modifications need to be made to the script files to log on to his system. ***** NOTE ***** The examples and explanations below use TELIX only as an example because that is the communications program *I* use, and am familiar with. Any communications program that can be invoked in a batch file and run a script unattended can be used. Sample scripts contributed by various nodes in CircuitNET International are included for other communications programs. 1) Choose an event in the SF.BAT file that controls the node CircuitNET is configured on. (If your system is controlled by a front door program, you can configure CircuitNET as an External event for the front door program.) :EVENT_A is chosen for this explanation. 2) Using an ASCII Text editor, read in the file NODEVENT.BAT betIen the :EVENT_A label, and the GOTO LOOP command, and edit the paths to conform to how your system is configured. (If you aren't using TELIX, you will need to replace the lines that call TELIX with the appropriate commands for your communications program.) 3) Configure your communications program to upload and download from the CIRCUIT\MAIL directory. In Telix, make a dialing directory entry for your host's BBS. The script to link is CNMAIL, and the password must be entered. (The sample Telix script obtains the password from this entry.) 4) Enable the event chosen to run at the time your host has scheduled your mail run. *** NOTE *** If you are going to use a two call system, then the event needs to be broken into 'send' and 'receive' events. The line by line explanation of NODEVENT.BAT below identifies where the break would need to be made. Separate scripts would be used for the send and receive calls to the communications program, and in Telix two dialing directory entries would be needed. The NODEVENT.BAT Explained: :EVENT_A ECHO OFF C: CD \SF\CIRCUIT\MAIL REM Change to mail drive and directory to keep filenames REM shorter on the command lines. IF EXIST HOSTNODE.ZIP PKUNZIP HOSTNODE REM If the file hasn't been renamed later in this event, REM it wasn't sent. so unzip it to append the new mail to REM the existing packet. C: CD \SF\CIRCUIT REM change to the drive and directory where CIRCUIT.CFG is. PRIMER REM Primer does NOT have to reside in the current directory. REM It may be in the PATH, or invoked with a full pathname. REM this applies to all of the CircuitNET programs. EXTRACT /Node=HOSTNODE REM This command line format extracts to a single node, and REM bypasses the NODES file. *** NOTE *** From this point to the GOTO LOOP would be included in the Receive Mail event for a two call system. The dialing script would be changed to DIAL2.SLC to dial the entry with the download mail script in place of the upload mail script. ************ C: CD \TELIX REM Change to the drive and directory of your comm program. REM Telix is configured to upload and download from the REM CIRCUIT\MAIL directory so moving files is not required. REM If your communications program is NOT configured to REM upload and download directly from the CIRCUIT\MAIL REM directory, then HOSTNODE.ZIP needs to be copied to the REM appropriate directory. TELIX /SDIAL1 REM This line tells Telix to start up and run the script REM 'DIAL1.SLC'. The script dials entry number 1 in Telix's REM dialing directory, and turns over control to the script REM linked to that entry when a connection is made. The REM DIAL1 script provided redials indefinitely, but can be REM configured to try a limited number of times if desired. C: CD \SF\CIRCUIT\MAIL REM Change back to the mail directory to shorten pathnames. IF ERROR LEVEL 1 GOTO NOT_SENT COPY HOSTNODE.ZIP HOSTNODE.DB4 DEL HOSTNODE.ZIP :NOT_SENT REM This error trap will rename the file to indicate that REM your comm program did not encounter an error sending the REM file. Save the file rather than killing it long enough REM to give your host a chance to request a resend if needed *** NOTE *** At this point, a GOTO LOOP would be inserted to end the send mail event for a two call system. The receive mail event would start at the preceding note, and include the following commands. ************ C: CD \SF\CIRCUIT REM Change back to the drive and directory where CIRCUIT.CFG REM is located. IMPORT REM Import the mail downloaded from your host. If there was REM no mail, Import will detect that, and log the REM information in the status report, and the log file. GOTO LOOP There is nothing that prohibits other commands from being included in the event such as bulletin generators to notify your users when the new mail has arrived, or prohibits removing redundant commands (such as changing drives if you have everything on the same drive.) This is simply a *generic* event for you to build upon. If you wish to link your mail event to the internal message packing event, you would put these commands in SFMSGPAK.BAT which executes following Event M if it exists. Changing from node to host Configuration There is one change needed in your CircuitNET configuration for hosting from a single node, and one additional text file named NODES, and one additional program that requires configuration. i.e. MAILCALL If you have multiple nodes, refer to the section on Multi Node operations. 1) Invoke CONFIG, and go to the sub-menu for (B)BBS info, and change the HOST BBS flag to TRUE. And save the changes. 2) In the CircuitNET system directory, create a text file named NODES, which contains the node id's of your dependent node(s). 3) Change to the CircuitNET system directory and invoke MAILCALL EDIT. (A)dd records for each of your dependent nodes using the name they will be logging on under, and the full name of the packet file to send to them. Refer to Mailcall.Doc for more about editing MAILCALL.DAT. Batch files There are Two additional batch files, and two changes to your existing event required to host another node. 1) Changes to your existing event: a) Following the IMPORT command line add the following commands: EXTRACT LOCK REM The LOCK parameter is required on the last EXTRACT REM of the event as it it not automatically selected as REM it is when HOST is configured as FALSE. IF ERROR LEVEL 133 GOTO SINGLES REM Error level 133 is returned if EXTRACT does not find REM enough disk space to extract for all of the nodes REM listed in the NODES file. If Error 133 is REM encountered when extracting for a single node, REM files will need to be deleted to make room. See REM the troubleshooting section for more info. :RESUME REM The Resume label is only needed if there Ire REM existing commands betIen the IMPORT and GOTO LOOP GOTO LOOP :SINGLES EXTRACT /Node=firstnode EXTRACT /Node=secondnode EXTRACT LOCK /Node=LastNode REM Replace "firstnode", "secondnode", "lastnode" with REM the nodes listed in the NODES file. Each node REM added later to the nodes file, would require a REM corresponding command line under the :SINGLES label. GOTO RESUME REM Could be GOTO LOOP if :RESUME wasn't needed. b) Following the IF EXIST HOSTNODE.ZIP ... Statement at the beginning of the NODEVENT.BAT commands, add corresponding IF EXIST NODEID.ZIP PKUNZIP NODEID commands for each node id in the NODES file. The batch file(s) that send the packets will be responsible for renaming the packets if successfully sent. 2) SFINIT.BAT file: This Batch file executes before Spitfire resets for the next caller. The following commands need to be added to check for an uploaded mail packet from a dependent node, and import it. IF NOT EXIST C:\SF\CIRCUIT\MAIL\YOURNODE.ZIP GOTO NOMAIL REM Skip over the import command is there's no mail C: CD \SF\CIRCUIT REM Go to the directory with CIRCUIT.CFG IMPORT REM Import the mail Refer to the Troubleshooting section for REM details on error levels returned for error trapping if REM desired. :NOMAIL REM continue with your existing SFINIT.BAT file, or return REM control to Spitfire. 3) SFSECxx.BAT file: This batch file executes as soon as a user with a security of 'xx' logs on. Most hosts have a specific security level for their dependents nodes when the call for mail. (The dependent BBS's have a separate user account from their sysop's account under their node ID.) This makes SFSECxx.BAT the ideal place for mail pickups. This is by no means the ONLY setup for distributing the mail to your dependents. SFMESS.BAT, SFMAIN.BAT, SFFILE.BAT, an unused :DOOR_x label in SF.BAT, or a frontdoor program can all be used to accomplish the goal of sending the right packet to the right node. The simplest method would be to simply configure the CIRCUIT\MAIL directory as one of Spitfire's file areas, and let the nodes download and upload their packets as they would any other file. ECHO OFF COPY SFDOORS.DAT C:\SF\SFEXTEND\SFDOORS.DAT :LOOP C: CD C:\SF\SFEXTEND SFMNUEXT IF ERROR LEVEL 48 GOTO EXTENDZ ... REM Most of the IF ERROR LEVEL statements removed to save REM space as only 0, 1, 2, & 4 are used for mail REM transfers. Refer to SFEXTEND documentation for REM information on setting up extension A for downloading REM mail, and Extension B for uploading mail. IF ERROR LEVEL 6 GOTO EXTENDC IF ERROR LEVEL 4 GOTO EXTENDB IF ERROR LEVEL 2 GOTO EXTENDA IF ERROR LEVEL 1 GOTO LOOP IF ERROR LEVEL 0 GOTO END :EXTENDA MAILCALL C:\SF\EXTERNAL\SFEXTDNA.BAT REM The batchfile specified on the command line does not REM need to be one that Spitfire normally uses for external REM transfer protocols, only one that can make use of the REM same parameters as Spitfire passes to it's external REM protocol batch files. The batch file used should check REM for a successful transfer, and rename the packet to REM indicate it was picked up. Refer to MAILCALL.DOC for a REM more detailed explanation. IF ERROR LEVEL 250 GOTO FATAL_A IF ERROR LEVEL 2 GOTO LOOP IF ERROR LEVEL 1 GOTO NOMAIL REM Refer to MAILCALL.DOC for details on these and other REM error levels it returns. Suffice it to say that all REM fatal errors are greater than 250, error 2 is "User not REM in Mailcall.dat", and Error 1 is "Mail packet not found REM to send." GOTO LOOP REM Fall through to here is packet was sent successfully. :NOMAIL C:\SF\EXTERNAL\DSZ port 2 sz -mrr NOMAIL.ZIP GOTO LOOP REM This sends a very small file named NOMAIL.ZIP to REM indicate that the lack of mail was not a failure of the REM dependent's event, but rather there was no packet built REM for that day. :EXTENDB CD C:\SF\CIRCUIT\MAIL C:\SF\EXTERNAL\DSZ port 1 rz -mrr GOTO LOOP REM Receive file directly into The CIRCUIT\MAIL directory. REM You may wish to add commands to make a copy in a safe REM place if you are of the paranoid persuasion. :END *** NOTE *** In addition to setting up your system to function as a HOST you must also assist your dependent nodes with Scripts, conference listings, network rules, and provide any other information they may need to reliably echo mail from your board. Echoing from your system will be subtly different from echoing with any other Host, and this documentation cannot anticipate your unique situation. ************ SYSTEM OPERATIONS This section is an overview of various aspects of CircuitNET software operations. The appendix on Basic Concepts is a detailed discussion of netmailing in general, and CircuitNET software based networks in particular. The Network A CircuitNET Software based Net-Work is inherently a tree structured system. The software assumes that there is one and only one path to any other node in the network. The structure consists of one ROOT node, (Generally referred to as the "National Host" or "National Hub"), Several HOST nodes, and END nodes. The ROOT and HOST nodes are "way-stations", or "switching stations" for network messages, and store messages that are "in transit" and distribute them to more than one other node. END nodes only exchange messages with their HOST. In addition to the technical limitations that mandate a tree structure, the administrative body of each network may have other requirements that affect the network structure, and where your BBS fits into that structure. Processing Mail There are three stages of processing involved in CircuitNET software. Conversion from the BBS's message format to CircuitNET format, Sorting of messages in CircuitNET format into transfer packets, and converting messages from CircuitNET format back into the BBS's message format. These functions are performed by PRIMER.EXE, EXTRACT.EXE, And IMPORT.EXE respectively. PRIMER: Primer's function is to identify messages flagged as net-mail in the BBS's message area, and convert ones that haven't already been sent into CircuitNET format. It checks each message for routing information in the subject field, and determines if the message is routable. If the message can be sent, Primer assigns it a unique network number, identifies the thread it is part of, (if applicable), and adds the node of origin and destination (if routed). The message is then added to any other "in-transit" messages in the work directory to be processed by EXTRACT. Once PRIMER has converted a message to CircuitNET's format, CircuitNET considers it to be "In-transit" until it reaches an end node, or it's destination. EXTRACT: Extract selects messages from the "in-transit" holding area, and builds one or more transfer packets. It performs several tests on each message to determine if it should be included in a specific packet. The tests include checking to see if the origin or last seen nodes are among the nodes accessible through the node the packet is for, checking to see if it is routed to a node accessible through the node the packet is for, and checking that node wants the conference the message is for. If the message passes all of the tests, then it is included in the packet. If it fails anyone of them, it is ignored. IMPORT: Import checks each message it processes against a history file to reject any duplicate messages. It also determines which BBS message conference the message belongs in, and assigns the message to one of three categories. The message has reached it's final destination, it is "just passing through", or It's both. In the case of an end node, There is nowhere to pass a message on to, so import ignores messages that would otherwise be "just passing through". For Host nodes, messages which haven't reached their final destination, are added to those in the holding area, and messages which pass the tests for being converted to the BBS's message format are added to the appropriate BBS message area. Batch files CircuitNET software is designed to work in and in conjunction with batch files. This gives a great deal of latitude in the way CircuitNET works on any particular BBS. Very basic batch files are provided as samples, but CircuitNET also provides a multitude of Error level exit codes that can be tested in batch files. I leave it up to your imagination and the list of exit codes as to how you make use of them. Mail transfers CircuitNET Software does NOT contain any communications routines, and does not concern itself with how the transfer packets are moved from one node to another. The utility MAILCALL.EXE is provided as a means of matching a caller with a packet file, but even there, the actual file transfer is accomplished by a batch file based on Spitfire's External protocol batch files. Sample batchfiles, and sample scripts for some of the more common communications programs are provided to assist you in transferring the mail, but are not the only way the transfers can be accomplished. The means of transferring the mail packets must be co-ordinated with your host, and any means that can be agreed upon is the means that should be used. Communications programs CircuitNET software does NOT contain any communications routines. It relies upon your choice of communications program to transfer the files from one node to another. As of this writing, the three most common programs used to transfer mail packets are Telix, Qmodem, and DSZ.COM. DSZ is generally used in conjunction with Mailcall in a host configuration where a phone call is ansIred, while Telix, QModem and other terminal packages are generally used where a phone call must be made. Some Hosts have Front End programs which allow "FREQ'ing" a mail packet if you have that capability, but a front end is NOT required for CircuitNET. Any Communications program that is capable of making an unattended phone call from a batch file will do. The fact that the Author of this document uses Telix in the examples is not to be construed as an endorsement of Telix as the preferred means of transferring the packets. It is merely the program with which the author is most familiar. FILE EXPLANATIONS Directories CircuitNET Software needs to know where certain files are located, and expects certain files to be in certain directories. The following is a discussion of what directories CircuitNET Software utilizes, and what each directory is utilized for. CircuitNET directories These are the directories that are peculiar to CircuitNET. Mail Directory The MAIL directory is where EXTRACT.EXE builds the message packet(s). It is also where MAILCALL.EXE will look for the filename you specify to be sent to a specific username. Normally you will see only files with a Node Id for a name and the extension '.ZIP', but during execution of EXTRACT.EXE a .CND and a .CNP file will be built for each node being extracted for, plus PKZIP will normally use this directory for it's temporary file while zipping the packet. A good estimate of the amount of space required in this directory, is to multiply the file sizes of the finished packet(s) by 3 to get the amount of space that needs to be free in this directory for EXTRACT to do it's job. Work Directory The WORK directory is where "Messages In-Transit" are held, and where IMPORT.EXE unzips incoming packets to. For a Host node, there will normally be two files in this directory named MESSAGES.CND and MESSAGES.CND. For an end node, the files only exist from the time that PRIMER.EXE runs until EXTRACT.EXE is done building the packet for the host. While IMPORT.EXE is importing messages, there will also be a CND and CNP file with your Node Id as a filename. Import deletes then when it is done with them. System Directory The CIRCUIT or System directory, is where the Dossier Files, outbound history files, CNCONFS.CFG, and CNROUTES.LST are stored. It is normally also where CIRCUIT.CFG and the executable files are kept, but it is not absolutely necessary that they be kept there. The CIRCUIT.CFG file in the current DOS directory will be used when each module is invoked, and the directories defined in the CIRCUIT.CFG file will be used. SpitFire Directories Since CircuitNET is designed to work directly with the Spitfire message base, it needs to know where some of Spitfire's files are to be found. System Directory CircuitNET uses Three (3) files in the Spitfire system directory. SFMCONF.DAT, SFNODE.DAT, and SFDOOR.DAT (or equivalent). SFMCONF.DAT and SFNODE.DAT are used by CONFIG.EXE which also uses the SpitFire WORK path from SFNODE.DAT to find SFSYSTEM.DAT in order to initialize the Sysop names, and obtain the number of users alloId. SFMCONF.DAT is updated by CONFIG.EXE with any changes made in the message conference configuration menu. PRIMER.EXE uses SFMCONF.DAT to get the old message purge date for each net-mail conference if PRIMER is to kill old messages. PRIMER ignores SFMCONF.DAT if the kill old message feature is turned off. SFDOOR.DAT or one of the equivalent files is used by MAILCALL.EXE to select the mail packet to be sent, and find the parameters needed to be passed to the batch file which does the actual transfer of the file. Work Directory As stated above, this directory is only used by CONFIG.EXE, and is obtained from SFNODE.DAT. Message directory Spitfire's message directory needs to be know for obvious reasons. Other than messages, PRIMER and IMPORT both 'lock' this directory by creating a file named WORKING.CN while they are processing messages. The file should only exist while PRIMER or IMPORT is running, and should be removed when they are complete. Both PRIMER and IMPORT work with a history file for each CircuitNET conference with the extension '.HST', plus SFMSG00.HST for "other" conferences. Work Files The two files named MESSAGES.CNP and MESSAGES.CND in the CircuitNET WORK directory are a holding area for "Messages In- Transit". A message is considered In-Transit from the time that PRIMER converts it to CircuitNET format, until it reaches it's final destination. Each node it passes through, (including the node it originated on), collects one mail cycle's worth of messages in the work files, until EXTRACT has processed them to all nodes being serviced. For an End node, only the messages that PRIMER copies from the Spitfire message base are involved, and only for as long as it takes for EXTRACT to process them. For a Host node, the work files are a little more important. As the messages from each dependent node are imported, any have not reached their final destination, (i.e. messages routed TO: the host node), and are not rejected as being duplicates, are added to the work files. PRIMER adds any messages entered locally, and then EXTRACT builds outgoing mail packets from the work files. When the last packet in the mail cycle has been built, EXTRACT deletes the work files so the cycle can begin again. Mail Packets A Mail packet is essentially a "copy" of the work files with unwanted conferences, and duplicate messages purged out. Each packet is a compressed file containing a .CND file, and a .CNP file. CircuitNET Software is constructed to use PKWare compression utilities, although it is possible to use other compression utilities by use of batch files named PKZIP.BAT and PKUNZIP.BAT provided the extension '.ZIP' is used so IMPORT.EXE will recognize the presence of a packet. History Files CircuitNET 3.11 changes the duplicate rejection scheme from prior releases. The change involves the use of history files which have the extension of '.HST'. There are Three different history files used, of two different types. There are the conference history files, and the node history files. The Conference History files are kept in the SpitFire message directory. There is one for each conference used by CircuitNET, and one for all conferences that are NOT carried by the node. SFMSG00.HST is the name used for the "all others" history, and SFMSGxx.HST is matched to the rest of the SFMSGxx.* files for the conferences carried by the BBS. The conference History file size is controlled by the "Max History per Conference" value configured in CIRCUIT.CFG. Once the maximum number of history entries for each conference is reached, (Or double the Maximum for SFMSG00.HST), each new message Primed or Imported replaces the oldest history record in the file. Primer does NOT do any duplicate rejection on outbound messages, and only records the history information for threading purposes. Import checks each incoming message against the appropriate history file and rejects duplicates and links threads based on the information therein. Obviously the more history kept, the better the duplicate rejection, and the more complete the threading. On the down side hoIver, the larger the history file, the sloIr Import runs, because of decreased memory available for processing large blocks of incoming messages at one time. The NODE history files are used for outbound duplicate rejection. One is created for each node extract builds a packet for, and kept in the CircuitNET System directory. The file Size is not as rigidly controlled as the conference histories, and purging of old history records is based on the number of days since the message was sent. The number of days history to keep is derived from the Maximum History value that controls the size of the conference history files. The Maximum History value is divided by 64 to give a minimum of 8 days history, and a maximum of 32 days. (The number of days is rounded down to the nearest integer value.) Only messages which pass all other tests for inclusion in a mail packet are checked against the node history file to see if it has already been sent to that node. Then all messages are added to the history file with the date they Ire sent. (Rejected messages get added with a new date to prevent problem messages from ever being resent.) (Note: Incoming messages from a node are NOT included in the node history file as they should never pass the tests for inclusion in the packet in the first place.) Dossier Files Each node messages are extracted for needs a dossier file in the CircuitNET System directory with the conferences that are to be echoed to that node. IMPORT.EXE will add any new conferences it sees to the Dossier file for the node that built the packet, and EXTRACT.EXE will add conferences if it finds a message routed through a node that doesn't already have that conference in it's Dossier. Import will also delete conferences from a Dossier file if it encounters a message that requests such deletion. Extract never deletes conferences from dossier files. WORKING.CN Both Primer and Import manipulate the conference history files by reading them into memory, and then re-writing the entire file when done with it. In order to prevent multiple copies of Import from trying to update the same history file or Import and Primer from writing contradictory changes to the same file, a 'key' file is used to lock the entire Spitfire message directory from use by more than one CircuitNET module at a time. The File is named WORKING.CN, and Primer and Import both will look for the file before they begin processing. If it doesn't exist it is created to lock out another module from starting, and if it does exist, the program will pause in a loop for 10-15 minutes checking for the file every few seconds. If the file is removed before time runs out, then the program replaces it to claim the message directory and proceeds with processing, or it puts a notice in the status message that it encountered the key file which didn't clear in the allotted time. CNROUTES.LST CircuitNET provides the capability to 'route' messages to a specific node. In order to know which packet a routed message should be included in, it refers to CNROUTES.LST. This file is a pure ASCII text file, with <Destination>,<node_to_Route_through> on each line. IMPORT.EXE builds this list by looking at the true origin, and last node to process each incoming message. Every packet imported is used to build a new list in memory, and when the entire packet has been processed, any existing routing list is compared to the new list in memory, and Destinations not represented in the packet processed are added to the new list in memory. Once the new information and the old (unchanged) information is combined in memory, the entire file is over- written with the new list. IMPORT has no way of knowing how long it has been since a message was received from a specific destination, and whether none have been received because the node is no longer active or just didn't have any message traffic for that day, so it NEVER deletes a destination once it has been added. Deletions must be done manually with a ASCII text editor periodically as node numbers are changed because of registrations or moves, or for nodes that drop out of the network. Inactive nodes present no particular problem other than taking up space. CONFIG.EXE Config is how you maintain CircuitNET's configuration file. Config defaults to a White on Black color scheme, but will accept the command line parameter 'COLOR' to switch to a White on Blue color scheme for those who prefer less contrast. Config automatically selects one of four possible operating modes, based on what files it can find when invoked. Config first looks for an existing file named CIRCUIT.CFG in the current DOS directory. If the file is a version 3.0x format file, config automatically converts the file to 3.1x format, and asks for the additional information needed. Otherwise it goes directly to the main menu. If config doesn't find CIRCUIT.CFG it looks in the parent directory of the current DOS directory for SFNODE.DAT. If it is not found, Config will ask where SFNODE.DAT can be found. Once it finds SFNODE.DAT, it looks for SFSYSTEM.DAT and asks for directions if it cannot be found. Using the information from SFNODE.DAT, and SFSYTEM.DAT and some default directory names, CONFIG will ask if you want each directory it can't find Made or Re-entered, or if you want to abort Config. It will then ask several questions, (with suggested responses for everything except Node Id), and eventually deliver you to the main config menu. The Main Menu: Since all possibilities eventually lead here, I guess I should explain what's going on here. The main menu presents you with 4 choices: [C] - Configure CircuitNET Information. [M] - Configure/Add Message Conferences. [S] - Configure Spitfire (Sysop Names/net-mail Toggle) [Q] - End the Program The Quit option should be pretty much self explanatory, so I'm just going to ignore that one, but since I'm at the bottom of the list I'll go backwards. [S] This will take you to another menu with 6 choices: [R] - Sysop Real Name: The name you put here, (and save to CircuitNET), is the name which will appear on your messages in the network. It is also the name that IMPORT.EXE will look for and swap back to your sysop logon name. [U] - Sysop User Name: The name that appears here, is the name that Primer will look for and change to the name above on messages it puts into the network. This is also the name that "Sysop ALL", "Sysop <NodeId>", and the name above will be converted to by IMPORT.EXE. It should therefore be the name you normally log on to the BBS with, (or your mail door uses to determine which messages are TO: You) [N] - net-mail will be used: Should be True if you want people to be able to tag messages for net-mail. If it's False, you will be able to import network messages, but won't be able to send any. [S] - Save Changes to Spitfire Only SFSYSTEM.DAT will be updated to the values shown. CIRCUIT.CFG will remain unchanged (Unless saved later from the [C] - Configure CircuitNET Info menu. This should therefore be the LAST changes you make if you do not want Spitfire and CircuitNET to agree on the Sysop's Real Name. See note to SFMail users below) [C] - Save changes to CircuitNET The Sysop Names displayed will be saved into CIRCUIT.CFG only without changing the values used by Spitfire. (See the note below if you use SFMail.) [B] - Save changes to both SpitFire and CircuitNET The values displayed will be written to both CIRCUIT.CFG and to SFSYSTEM.DAT. NOTE to SFMail users. The author of SFMail keys the registration to the "Sysop Real Name" saved to SFSYSTEM.DAT. If you wish to be known by an alias in the network, and log on the the BBS as "Sysop", (or a different alias than you want shown in the network), then you need to NOT use the [S] option or the [B] option, and only save changes to CircuitNET. Doing otherwise will either cause SFMail to crash, or cause the name you registered SFMail under to be used on the network. To return to the Main Menu select Q for Quit. [M] - Configure/Add Message Conferences The menu displayed when you select this option is basically the same as that displayed by ALT-R from the spitfire "Ready for use" prompt. Therefore I will only cover four of the options which either don't exist, or function differently than the SpitFire ALT-R menu. [#] - Conf Access Type: The only difference here is the notation. SpitFire Spells out "Equal to user security", and "Equal To Or Greater Than User Security", while Config uses Either the mathematical symbols '=' or '>=' for "Equal to" and "Greater Than or Equal To". The function is the same, but the symbols Ire used to save space on the display. [A] - ADD a conference [D] - DELETE a conference. Both the Add and Delete Functions only work on the highest numbered conference. Inserting a conference or removing a conference from the middle of the file is not supported. With large numbers of conferences, properly inserting a conference, or removing one from the middle involves a great deal of time in moving files to keep them in synch with the conference descriptions. Config will automatically seed new conferences, and update all .LMR files to match the SpitFire 3.2 standard. It does NOT hoIver do the reverse, and delete the conference files along with the conference description. The files are left intact so that they can be renamed to a new conference number if the description they match was moved to a new record. Deleting and re-adding a conference will therefore NOT remove messages which do not match the new description. *** IMPORTANT NOTE *** DO NOT, repeat DO NOT insert or delete conferences through Spitfire! Doing so will cause the conference codenames to be shifted away from the matching descriptions. The codenames are stored in a parallel file which matches SFMCONF.DAT record for record. If you need more conferences added to Spitfire, CONFIG can add non-CircuitNET conferences simply by leaving the Conf. Codename field blank. ********************** [C] - Conf. Codename: This option updates a separate file from all of the other fields shown on the Conference Configuration menu. CNCONFS.CFG is kept in the CircuitNET System directory, and matches the SFMCONF.DAT record for record. If this field is 'NC' (meaning 'Not Configured'), or Blank, then CircuitNET ignores the conference. Any other Alpha-Numeric entry will be treated as a network conference codename. (The name by which the conference is known to the software.) As only upper case information is accepted, case is not critical. and spaces will be stripped out. Spelling hoIver is important! If you mis-spell the codename assigned to a conference, then you have effectively created a conference that only you carry, and one BBS is not much of a network. When you have made all necessary changes to your message conferences, press Q to quit, and you will be asked if you want to save the changes. 'Y' or <Enter> will write all changes to SFMCONF.DAT, and to CNCONFS.CFG, and check each conference to see if it requires seeding, or if the .LMR file requires updating to SF 3.2 specifications. A non-net-mail seed message will be written to each conference that has no messages already, and empty last read pointers will be appended to any .LMR file that has feIr records than the maximum number of users alloId. (SpitFire 3.2 pre-builds .LMR records for all allowable users. The larger .LMR files do not affect the operation of earlier Versions of Spitfire 3.x. Existing last read pointers are not changed by Config.) [C] - Configure CircuitNET Information This choice from the Main Menu takes you to a menu with Two Choices: [P] - CircuitNET Paths and FileNames The paths Ire discussed above, and The activity and error logs can be any valid filename. It is not recommended that they be the same file, although it is permitted. Many nodes use SpitFire's HEYSYSOP.LOG so activity reporting is accessible remotely. (The minimum logging is a status report as a private message in conference #1 addressed to the Sysop User Name in CIRCUIT.CFG, so remote access to information logged to the files is not generally needed.) New entries are checked for validity before being accepted. [B] - BBS Information (Node ID) This choice takes you to the BBS Information Configuration Menu. This menu is the only one isn't relatively self explanatory. [N] - Node ID The Node ID field is where you tell the software several things. Where messages entered on your BBS come from, What file name IMPORT.EXE should look for, and which routed messages and "Sysop WildCard" format messages are meant for you to read. The Node ID is assigned by the network you are joining, and should be obtained from your host. The node ID is used for several filenames through out the network, so it is limited to the characters alloId by DOS in an unambiguous filename. (i.e. no '*','?','/','\','<','>' characters.) what you enter will be converted to upper case, and have any spaces stripped out before it is saved. [#] - Msgs/Conf to keep a history on = This field has several effects on the operation of the software. It controls both the maximum size of the conference history files, (File size = MaxHist * 8 Bytes), the number of days to keep outbound histories for each node extracted to, ( Days = MaxHist DIV 64), and how effective net-wide threading is, ( at least one thread element must be represented in the history file for the thread to be linkable). A minimum of 512 messages (8 Days) and a maximum of 2048 messages (32 Days) are permitted. Any value betIen those two is acceptable. The default is 1024 (16 Days). Since both Primer and Import read the entire conference history files into memory, the larger this value, the less memory they have available for manipulating more than one message at a time, so they have to read in and process smaller blocks of messages for processing. This will affect processing speed on importing of large packets with messages for many conferences, more than it will Priming, or packets with few conferences represented. If you are concerned about processing times, you will need to find the optimum value for your system that handles rejection of duplicates and threading adequately, without increasing processing time beyond what you consider acceptable. [K] - Kill Old Msgs When Priming This feature exists because some of the message packing facilities do NOT kill old messages, and old message thread elements properly. Since Primer reads every message in each net-mail conference anyway to find un- sent messages, you can have it also check the message date against the Old Message Purge Days you have configured in SFMCONF.DAT. If this is set to TRUE, Primer will flag ALL old messages as being explicitly deleted, and disconnect each message from it's thread, and flag it has having been received. This will force any message packer to remove the message unless it is the sole survivor in a conference. Primer will recognize purge dates as low as one day, while The internal SpitFire message packer will treat any value of less than 5 as 120 days. Having this feature turned on gives Primer more work to do, and slows it down marginally. Turning this feature to FALSE will speed Primer up some if you are happy with the way the message base packer you use handles old messages. [H] - This BBS is a HOST This flag changes how IMPORT and EXTRACT deal with the work files. If you are not hosting other nodes. (i.e. building packets for more than one other node.) then this should be set to FALSE, so that IMPORT.EXE will not waste time or disk space writing copies of the incoming messages to the work files only to have them bypassed by EXTRACT.EXE and deleted. This causes Extract to default as if you specified 'LOCK' on the command line to delete the work files when it is done. Setting this field to TRUE causes IMPORT to write messages to the work files, and EXTRACT to leave those files intact when it is done, so that mail from dependent nodes can be combined with mail from the host node and distributed to all of the nodes you are linked with. YOU are then responsible for specifying the 'LOCK' parameter on the command line for the last extract of the day to dispose of the files, or to manually dispose of them at the appropriate time. [P] - BBS Phone number [B] - BBS Name (and on registered copies) [M] - City/State/Motto or Whatever These three fields are combined by Primer to build an identifying tagline for all messages that originate on your BBS. All will accept any Alpha-Numeric ASCII ('True' ASCII, NOT the full IBM Extended Character set, or Control characters.) The two lines below are an example of how the tagline is built: CircuitNET 3.11: Node: <NODEID> Phone <BBS Phone> <BBS Name field> <BBS Motto Field on registered versions> Once you have made changes on the sub-menus of the Configure CircuitNET information menu, and select Q to return to the Main Menu, you will be asked if you want to save any changes made. 'Y' or <Enter> will re-write CIRCUIT.CFG with any changes made. *** NOTE *** The information changed includes the Sysop Names displayed on the Configure Spitfire (Sysop Names) option from the main menu. Any time changes are save to CircuitNET, the Entire Configuration file is re-written with whatever is in memory, and NOT just the changes that Ire made on a specific menu. ************ NODES File The NODES file is where Extract looks for the node(s) it is to build (a) mail packet(s) for. If Extract doesn't find a /NODE= command line parameter, it looks for an ASCII text file named NODES in the CircuitNET System Directory. In the file it expects to find a list of Node ID's separated by carriage returns. (i.e. one node ID per line.) Extract Builds a mail packet for each node it finds in the file. (Note: Each additional node listed increases EXTRACT.EXE's disk space requirement in the CircuitNET MAIL directory by the size of the work files. Too many nodes will cause Extract to abort with an error level of 133.) If Extract finds a /NODE= command line parameter, it bypasses the NODES file and builds only the packet for the node ID specified on the command line. Packet compression CircuitNET Software expects to find PKZIP.EXE and PKUNZIP.EXE in the DOS search path. Because of the method used to shell out for packet compression, if PKZIP.BAT or PKUNZIP.BAT are found before the .EXE file is, then the batch file will be executed in it's place. EXTRACT.EXE does not check for an existing packet before shelling out, but IMPORT does. If you wish to modify the way the packets are compressed or uncompressed, you need only create a batch file with the appropriate name and place it where it will be found and executed before the corresponding .EXE file. In order to get Import to shell out, a file with your node Id and the extension '.ZIP' needs to be placed in the CircuitNET MAIL Directory. The following command line parameters would be passed to the batch files. From EXTRACT.EXE to PKZIP.BAT: %1 = -m %2 = <CircuitNET MAIL Dir><NodeID of packet to Compress> %3 = '@'<CircuitNET Mail Dir><NodeID of packet to compress>'.CMD' (Note: Extract appends to any existing .CMD file found to allow inclusion of other files in the mail packets.) From IMPORT.EXE to PKUNZIP.BAT: %1 = -o %2 = <CircuitNET MAIL Dir><Your Node Id> %3 = <CircuitNET WORK Dir> (Note: Import expects to find the .CND &.CNP files to process in the CircuitNET WORK directory when the shell returns control.) It should be noted that any changes in the compression utility used to build the packet needs to be co-ordinated with the other nodes involved. You cannot simply choose to send a packet in a non-Zip format to a node that is not setup to process it. How you deal with converting the command line information and determining the format of incoming packets, and select alternate compression formats is entirely up to your imagination and Skill in batch file construction. PRIMER.EXE Primer is used to convert messages from Spitfire format to CircuitNET format. In the process of finding and converting net-mail messages, primer marks each message as having been sent in the Spitfire message files, swap the name from the sysop's logon name to the sysop's real name, and parses the subject field for routing and conference management codes. If a routing code is found Primer checks the routing list to insure that it is routed to valid destination. Primer assigns each message a unique message number and a unique thread identifier and marks the message with it's true origin. Primer also updates the conference history file with the Unique number it assigned to the message matched to the messages internal Spitfire message number so that replies to the message from the network can be threaded to it. EXTRACT.EXE Extract is basically a message sorter. It checks each message in the work files against the dossier files, node history files, and routing list to determine if the message should be included in each nodes mail packet. Extract's most important function for end nodes is to Ied out duplicate messages that result from repeated uploads of the same reply packet from offline mail readers. For host nodes, the routing and selection functions gain in importance. IMPORT.EXE Import converts messages back into Spitfire format, and determines which messages are to be passed on to other nodes. Import is responsible for changing the Sysop's real name back to the Sysop's logon name, and will recognize several variations of messages addressed to "Sysop xxx" as being the equivalent of being addressed to the sysop's real name. The special formats are "Sysop" and either the keyword "ALL" or a node ID specification. The node Id Specification can be either an explicit node ID, or a DOS style wildcard. "Sysop All" will always convert to the sysop's log-on name, and be imported. Import will by-pass other Sysop messages if they do not match your node ID, and pass them on to the work files so they can be relayed to other nodes. (NOTE: If you are NOT configured as a host, then Import will not write ANY messages to the work files.) Import does one more thing with messages that will convert to the Sysop's logon name. I will "rescue" messages that are in conferences that are not normally imported by importing them as "comments to the sysop" in conference #1. If a message reaches your board, and is intended for you to read, then you will see it, even if you do not normally import that conference. MAILCALL.EXE Mailcall is a utility for host nodes to distribute mail packets to the proper nodes. It is covered in full in the separate file MAILCALL.DOC. It is NOT required for end nodes. APPENDIX A L I C E N S E A G R E E M E N T Shareware Version -------------------------------------------------------------------------- CircuitNET is not a Public Domain program and is not free. Non-registered users of CircuitNET are granted a 30 Day limited license to evaluate the suitability of CircuitNET for their particular requirements. Any usage of CircuitNET beyond the evaluation time period requires registration of each copy of CircuitNET used, according to the multi-net usage agreement. Use of non-registered copies of CircuitNET beyond the original evaluation period is prohibited. CircuitNET and its accompanying programs may NOT be modified in any respect, for any reason, including but not limited to, de- compiling, disassembling, reverse engineering, or editing of the EXE. This documentation may not be reproduced, transmitted, transcribed, or translated into any language, computer or otherwise, without the express written consent of Dave Stahl. You are free to distribute the PUBLICLY AVAILABLE shareware version of CircuitNET to others subject to the above restrictions and also the following: A. No fee is charged for its use. B. No remuneration may be accepted for CircuitNET. This does not apply to computer access charges the system operators ( Sysops ) of or organizations owning bulletin board systems, online services, etc. may charge subscribers. C. CircuitNET must be copied in unaltered form, complete with files containing license information, the FULL documentation and all accompanying files. D. License to distribute this program is granted to Shareware Houses & Disk Vendors, with the following conditions: ■ The files distributed MUST be the latest available, preferably from a CircuitNET distribution BBS. ■ The CircuitNET archive must be complete, and MUST be named with the author's ( Dave Stahl ) naming conventions. Commercial distributors of "Public Domain", "Shareware", and/or User Supported software may distribute CircuitNET subject to the above conditions only after obtaining WRITTEN permission from Dave Stahl. This condition statement supersedes all previous agreements. Please refer to registration/ordering section for additional information on registration, corporate site-licensing and related topics. -------------------------------------------------------------------------- L I C E N S E A G R E E M E N T Registered Version -------------------------------------------------------------------------- CircuitNET and its accompanying programs may NOT be Modified in any respect - for any reason - including, but not limited to: ■ Decompiling. ■ Disassembling. ■ Reverse Engineering. ■ "Editing" Of Compiled EXE. The documentation for CircuitNET may be translated into foreign languages ONLY with permission from Dave Stahl. The SHAREWARE license statement does not apply to the REGISTERED version of CircuitNET. The registered software of Dave Stahl is protected under United States Copyright and Trademark Laws. It must be treated just like a book with certain exceptions ( Below ) A. Dave Stahl authorizes the making of archival copies of the registered software for the sole purpose of backing-up your software and protecting your investment from possible loss. B. The medium on which the registered software is recorded is transferred to the customer, but not the title to the software. C. The Licensee may resell or transfer unmodified copies of the registered software provided the customer has registered from Dave Stahl one copy of the registered software for each one sold or distributed. The provisions of this software license shall also be applicable to third parties receiving copies of the registered software from the customer. The resale price of CircuitNET is not to exceed the price paid originally. D. Multi-Net usage Agreement: Each registered copy of CircuitNET can be used on up to 2 ( Two ) Bulletin Board Systems owned by you, regardless of the number of networks you run. This does not apply to Multi-Node BBS's, Nor to Subboards off the same BBS. Should you require a second registration, please see the registration form for details. E. Dave Stahl reserves the right to cancel your registration of CircuitNET upon proof of any aberration of the above outlined terms, particularlly those dealing with modifications. F. You MAY NOT form new network using CircuitNET software without CONSENT from Dave Stahl. This applies to local networks, as well as national or international networks. S T A N D A R D D I S C L A I M E R -------------------------------------------------------------------------- CircuitNET is provided AS IS without any warranty, expressed or implied. This includes without limitation the fitness to a particular purpose or application and any warranties of merchantability. While I tried to be as through as possible while debugging CircuitNET, Dave Stahl shall not be liable for any damages, whether direct, indirect, special, or consequential arising from a failure of this program or accompanying files to operate in a manner desired by the user. Dave Stahl shall not be liable for any damage to data or property which may be caused directly or indirectly by use of this program. In no event will Dave Stahl be liable to you for any damages, including any lost profits, lost savings or other incidental or consequential damages arising out of your use or inability to use the program, or for any claim by any other party. If you have a problem with CircuitNET please notify Dave Stahl, describing the situation & revision number/date. Registered users, please include the serial number found on your registered programs. -------------------------------------------------------------------------- THE ANATOMY OF A MESSAGE SpitFire Messages Spitfire maintains and manipulates messages with a system of parallel files. It maintains .PTR, .DAT, .IDX, and .LMR files for each conference. All of the files have a common file name consisting of SFMSG folloId by the number of the conference. CircuitNET deals only with the first three files. (CONFIG.EXE does create the .LMR file for new conferences but doesn't manipulate it in any way.) The .PTR file: Spitfire messages are separated into the header or pointer record, and the data records or message body. The .PTR file is where the header records for each conference is stored. The header record contains the information on who the message is to and from, when it was entered, the location and number of data records, an internal message number, and thread identification. It also contains a set of Flags that indicate whether the message is deleted, net-mail, received, or part of a thread. Essentially everything Spitfire needs to know about each message except what it actually says. The .DAT file: The SpitFire message Data File stores the text of the message in 128 byte blocks. EAch message is "rounded up" to the next multiple of 128 bytes. The .IDX file: Spitfire uses an index file to speed searches through the message directory. Each index record contains a code identifying who the message is to, who the message is from, and the message number and thread identification number. The to and from codes are simply 32 bit CRC's of the text in the to and from fields of the pointer record for the matching message. The .LMR file: Spitfire maintains one record in each .LMR file with the internal message number of the last message read by each user in each conference. ( With Spitfire 3.2 there is a record for each user allowed rather than for each active user. ) Circuit Net Messages CircuitNET uses a similar system to Spitfire's with the difference that CircuitNET doesn't require the index and last read files. It does need to keep track of a history of which messages have been moved in and out of each of Spitfire's message conferences. So CircuitNET adds one file to SpitFire's files with the extension .HST to keep the historical data in. CircuitNET uses the extension .CNP for it's pointer files, and the extension .CND for it's data files. The .CNP File: Like Spitfire, CircuitNET keeps the data in a separate file from the header records. CircuitNET uses much of the information from the Spitfire .PTR file to build it's pointer records, but there is information in the Spitfire record that CircuitNET doesn't need, and there is information that CircuitNET needs that is not in the Spitfire records. Also, some of the information that CircuitNET does get from the Spitfire record isn't as compact as it could be. So CircuitNET builds a record that contains everything it needs to re-construct a Spitfire message header, plus everything it needs to control the messages travels through the network, and at the same time is a small as possible. The end result is that SpitFire's pointer record is 64 bytes larger than CircuitNET's. The .CND file: CircuitNET's Data file is not organized in blocks, but in single bytes. Strings of repeated characters in the Spitfire data records are stored as three bytes, and trailing spaces are stripped out. (Repeated characters are represented as a identification mark, number of characters, and the character to repeat.) Short of an actual compression, as is done by archiving programs, this transfers the message text in as few characters as possible. M E S S A G E C O N T R O L C O D E S -------------------------------------------------------------------------- CircuitNET Message Control codes (MCCs). MCCs allow you or any user of your system to route messages to a specific node. In addition, the Sysop may REMOTELY modify his or her Dossier File on another system. ROUTING MESSAGES In order to route a message to a specific node, a user must enter the Route Specifier, which consists of TWO greater-than signs (>>) immediately folloId by the node number of the system that message is to be routed to, in the SUBJECT of the message. The Route Specifier, together with the destination node, comprise the Route MCC. Thus, if a user wanted to route a message to another user on node 801000, he or she would enter the message as normal, but would place the following in the subject of the message: Message to: Joe Blow Message From: Joe User Message subject: Hi Joe! >>801000 | | | +-- Node to Route message to. + ----- Route Specifier *NOTE: The FIRST character of the subject MUST be a letter. The rest of the message would contain the actual text of the message. Thus, the entire message would appear as below, and would be sent to all of your linked nodes, but would only be imported into node 801000: Message To: Joe Blow Message From: Joe User Message Subject: Hi Joe! >>801000 1: This is a routed message to node 801000. 2: 3: Sincerely, 4: 5: Joe User DOSSIER FILE MODIFICATION A Sysop of a CircuitNET system may REMOTELY modify his or her Dossier File on another system by using the Add and Delete MCCs. A CircuitNET Sysop may both add and delete conferences from his or her Dossier File. Adding a conference: Adding a conference simply requires sending a routed message IN that conference. Assign the desired codename to a Spitfire Conference, and then enter a routed message in that conference to be sent net-mail. Route the message to any node you know already echoes that conference. (Usually routing to your host is sufficient.) Address the message TO: Sysop <NodeId> of the node you route the message to. WildCard routing and Sysop specifiers are permissible. The desired conference will be added to ALL dossier files required for you to echo the conference betIen your node and the node the message is routed to. Deleting a conference: Remote deletion of conferences is more tightly restricted. 1: You can only delete conferences from the Dossier file for YOUR node on systems you echo directly to. You CANNOT delete conferences in nodes you do not build packets for. 2: The message must be FROM: the name given as Sysop User Name in Config. A message from any other name will produce an error message from Primer in both the Activity and Error log files alerting you to an "Unauthorized attempt to delete a conference", and the message will NOT be processed. The warning message will be repeated each time primer is run until the offending message is deleted, or until the Sysop User Name is changed to match the From: field in the message. 3: The Subject: filed must contain a routing specifier AND a deletion command. non-routed attempts to delete a message will be processed as a normal message and sent into the network, but will have NO effect on the dossier files. (i.e. SUBJ: >>MYHOST--BANANAS) 4: The last character of the codename to delete must be folloId by a space, or be the last character in the subject. Imbedded spaces are ignored. any text following the '>>' marker, (including the marker), will be removed once Primer parses the information so any text following the codename will be lost. 5: On the recieving end, the name of the Dossier file to modify must match the node ID of the true origin of the message. In other words, you cannot modify any dossier file except the one for YOUR node on a system that builds packets FOR you. (i.e. your host, or a direct dependent of your node.) NOTE: All traffic in the conference must cease, or the automatic update feature of IMPORT will re-add the conference. All message in the packet containing the deletion command will Import normally before the deletion is made, so the command can delete the conference it is sent in, but it must be manually removed from the affected dossier file on your end. (After the delete command is sent if it is in the affected conference. Any time if in another conference.) A P P E N D I X B B a s i c N e t m a i l C o n c e p t s -------------------------------------------------------------------------- NODE NUMBERING In order to maintain organization throughout ANY network, a system must have an address, or a unique identifier that distinguishes that system from another. In CircuitNET, this addressing technique is called Node Numbering. Each system using CircuitNET will have a node number. In the CircuitNET International Network, node numbers are assigned as follows: - Node numbers consist of the area code of the system's location, followed by a three-digit number denoting the number of the system. Thus, the first system in area code 801 would be assigned the node number 801001. - Any CircuitNET system which performs host duties is assigned a 000 number to their node number. Thus, the host system for the 801 area code is designated as 801000. Host Systems are usually the first registered CircuitNET systems in an area. CONFERENCE IDENTIFICATION Each conference used by CircuitNET must have a codename. This codename is used to match up conferences on different system whose conference configuration are not identical. For example, if System A has the CircuitNET Support Conference as Spitfire conference number one, and System B has it as Spitfire conference number nine, then there needs to be some way for CircuitNET to make sure that the mail from System A's conference number one is imported into System B's conference nine, and vice-versa. This is where CODENAMEs come in. Conference CODENAMEs are eight-letter mnemonics used to represent the name of a conference. By using a conference codename, conferences are more accurately represented on a system. Instead of having to maintain a database that represents each system's unique configuration, a more static method is provided by assigning each conference a codename that is used to denote which conferences are to be linked together. Thus, CircuitNET doesn't worry about matching conference number up, but rather concentrates its effort in getting the mail from one conference into another conference with the same CODENAME. DUPLICATE MESSAGES Duplicate messages occur when there are two or more messages which are exactly the same in any given conference. IMPORT compares each message being imported to those already in the software message conference and rejects any that would be duplicates. If there is no matching message in the spitfire message base then the message is imported. This may result in a resent message which is a message that was on a given board then deleted and then re-imported into that boards message base and then sent back out on the net. APPENDIX C This appendix is provided to those of you who like the technical aspects of CircuitNET. If you have any questions concerning topics above and beyond those covered in this manual, contact Dave Stahl and I will help you out in any way I can. SOURCE CODE AND RECORD STRUCTURES There are no plans to release the source code to CircuitNET to anyone. The record structures, however, will be released on a case by case basis to those who wish to write utilities to function with any of the Circuit Net files. APPENDIX D REVISION HISTORY -------------------------------------------------------------------------- April, 1992 - Copyright purchased from Gorilla Brothers Software by Dave Stahl Jan 1992 - Release Ver 3.11 - Rewrite of CircuitNET mail packet structure, duplicate rejection sceme reworked for better results, Node ID increased to 8, addition of .HST files for duplicate rejection, Outbound duplicate rejection added, NET wide message threading added, message routing expanded to now include wildcard message routing, SYSOP ALL message routing now added. Dec 1990 - Copyright purchased from Sean C. Burbidge by Gorilla Brothers Software. Release 3.04 - Fixed memory allocation problems and message conference size limitations introduced in release 3.01 of import, also enabled transparent conference routing and automatic dossier file updates. Release 3.01 - Added Duplicated Rejection facilities to IMPORT.EXE -------------------------------------------------------------------------- APPENDIX E Command lines, Exit Codes, and Troubleshooting PRIMER.EXE only recognizes three command line parameters: NOLOG: Reduces logging to the status message, and start/stop times in the activity log. Errors will be reported to the Error log with only a reduction in detail. BRIEF: The default logging level with the status report message copied to the log files. VERBOSE: For Primer only notification of errors is added to the default brief logging. EXTRACT.EXE Recognizes the same three logging level commands as does Primer plus three additional command line parameters: Nolog, Brief, and Verbose function basically the same as for Primer, with the exception of the verbose mode. For Extract verbose logging adds detail to reject notices, but extract does NOT notify you that it has rejected any messages. the only trace of outbound rejections is the error log entries. /Node=xxxxxxxx This command line causes Extract to bypass the NODES file, and only build one packet. Only the first occurrence of this parameter is recognized. LOCK This parameter tells extract that the mail cycle is complete, and that the work files are no longer needed. The work files will be deleted when extract is finished building the packet(s). If Extract encounters a fatal error, this parameter is ignored. If the BBS is configured as a HOST this parameter must be used. If the BBS is configured as an end node (i.e. "This BBS is a host = FALSE) this parameter is automatically set. HOST This parameter overrides the configuration host mode variable and preserves the work files. It is the functional opposite of LOCK. IMPORT.EXE Recognizes the three logging levels, plus one other command line parameter: NOLOG Import reduces the information in the status report message, as Ill as reducing the Activity log to start/stop times. Import will also stop reporting of which messages Ire rejected to the error log. BRIEF: In the default mode of Brief logging, Import reports the numbers imported by conference in addition to the totals reported in NOLOG mode. It also copies the same information to the Activity log. Minimal information is reported to the error log for rejected messages. VERBOSE: Import Adds information on each message imported to the Activity log, and expands the information on rejected messages in the Error log. (The format of the verbose activity log is compatible with NETBULL.EXE by Kenneth Rucker which generates a bulletin for your users.) HOST: Import does not write messages to the work files unless it is in host mode. Import uses the HOST variable in the CIRCUIT.CFG file as the default. This parameter can be used to force Import to write to the work files, although no command line facility has been provided to prevent it from writing to the work files if the BBS is configured as a host. Error Levels and trouble shooting: Primer.exe: Prime has two error exit levels 128 : CIRCUIT.CFG not found or unreadable. There are two possible causes for this error. Either Primer was invoked with the current DOS directory other than the one that contains CIRCUIT.CFG, or the CIRCUIT.CFG file as not compatible with version 3.11 of CircuitNET. (Either corrupted, or from an older version of CircuitNET.) Insure that your batch file changes to the directory that contains CIRCUIT.CFG, and if that doesn't correct the problem, you will need to re-build CIRCUIT.CFG with CONFIG.EXE 135 : Message base locked by WORKING.CN. Both Import and Primer use a file named WORKING.CN to "lock" the SpitFire message Directory. If you suffer a poIr failure or have to re-boot the system while Import or Primer is working, this file is not deleted as it should be. Primer and Import will loop until this file is deleted, or 10-15 minutes, or until any key is pressed. If the file is removed while they are looping they go ahead and execute, other wise they exit with a notice to the the status message and log files, and this error level. Normally this error level indicates that a run-time error or other program interruption cause the key file to be left behind. If WORKING.CN exists when neither Import or Primer is running, then it should be deleted. (Your batch file can delete the working file when the main Spitfire node is booted, but care should be used to prevent the file from being deleted when a module is actually working.) Another situation that can cause this error level is when the module that has the message area locked does in fact take more than 15 minutes to complete it's processing. Primer's processing time is much longer than the time Import will wait if you have many conferences and/or several conferences with great numbers of messages. For a 286/12 machine over 100 conferences, or over 10,000 messages total will push Primer's processing time beyond the time limit to wait for the Key file to clear. EXTRACT.EXE Extract only exits with an error level of 0, 128, or 133. 128 is generated when Extract cannot open or read any of the files it requires. The error log is used to report which file caused the problem. 133 is generated when Extract cannot find enough disk space to build the mail packets. If this occurs when extracting for a single node, files will need to be deleted or moved to make room in the CircuitNET Mail directory. If it occurs when extracting for multiple nodes then usually extracting for each node singly with the /NODE= command line option will be successful. IMPORT.EXE Import has the most extensive error exit reporting. 1 : Error level 1 is generated when there is no mail packet found to process. Import checks in the CircuitNET Mail directory for <nodeid>.ZIP before doing any processing. 2 : Error level 2 is generated if either the .CND or .CNP file from the mail packet are not found in the CircuitNET Work directory after returning from the shell to PKUNZIP. The most probable cause for this error is that the mail packet contained Zero byte files. Other possible causes include an error unzipping the packet, and insufficient disk space in the Work directory. 128 : Import could not find CIRCUIT.CFG or could not read it. 129 : Import could not find CNCONFS.CFG in the CircuitNET system directory, or could not read it. 131 : Import did not find enough memory to process the packet. Import requires approximately 256K to load, and then checks to insure it has enough memory available to read in the files it needs to process the message packet. 133 : Not enough space on work drive to run. Import did not find enough disk space on the drive that contains the CircuitNET Work directory to process the mail packet. 134 : Not enough memory to continue. Import ran out of available memory. This indicates that the mail packet contained information that caused it to build bigger lists in memory than it predicted it would need. Import leaves the .CND and .CNP file in the work directory in this case, and often simply re-zipping them and re-importing the packet will recover missed mail. (The rejection of the previously processed messages consumes less memory than processing them the first time did.) If that fails, removing TSR's and device drivers from memory is required to provide more memory for import to work with. 135 : Message base locked by WORKING.CN. See the comments under Primer for more information on this error. Import is susceptible to some of the same factors that would cause Primer to run longer than the time limit. i.e. large numbers of conferences, or a very large packet with messages to many different conferences. On a 286/12 machine a packet with over 2000 messages to 100 different conferences was required to cause import to run longer than the time another module would wait. 136 : Unable to Open/Create MESSAGES.CN? If host mode is active, and Import cannot open or create the work files, it will abort without processing any messages, and leave the packet .CNP/CND files in the work directory so that they can be re-zipped after the problem is corrected. Most probable cause of this error is Extract having the files open longer than Import's sharing code will re-try, or an orphaned file lock in the tables maintained by SHARE.COM. Re-zipping the packet and re-trying should correct the problem. R E G I S T R A T I O N I N F O R M A T I O N -------------------------------------------------------------------------- Once a registered user of CircuitNET, you are free to utilize the program as often as you wish. You will also be notified when a significant enhancement has been made to CircuitNET. Once registered, all upgrades are available for free. Upon the receipt of your registration you will be provided with your registered copy of CircuitNet which will allow you full access to all of the current net mail conferences. There are two ways to register. The first is by sending $20.00 (US) to Dave Stahl along with a registration form. You may then download your registered version from Quantum Leap! @ (408) 267-0631. Or, for an additional $5.00 (US), I will send you the latest shareware and registered versions of CircuitNET on disk along with documentation (on disk) w/Utilities. CircuitNET UPGRADES Once you have registered CircuitNET, future upgrades are free. Registered users desiring an upgrade may either download the new version from the CircuitNET Support BBS, or may opt to receive the new version on diskette. In such case, please send $5.00 (US) to Dave Stahl for handling costs. APPENDIX F: REGISTRATION FORM Remit Registration To: Dave Stahl 3158 Ross Ave San Jose, Ca, 95124 Qty. Description Each Total -------------------------------------------------------------------------- ____ CircuitNET Upgrade to version 3.11 on disk $5.00 _______ ____ CircuitNET Registration $20.00 _______ ____ CircuitNET Registration ( 360K 5.25" ) $25.00 _______ ____ CircuitNET Registration ( 720K 3.5" ) $25.00 _______ ____ CircuitNET Second Registration $10.00 _______ ____ CircuitNET Second Registration ( 360K 5.25" ) $15.00 _______ ____ CircuitNET Second Registration ( 720K 3.5" ) $15.00 _______ --------------------------------------------------- Subtotal _______ All orders outside US & Canada add $5 Shipping Shipping _______ Add $5 for Currency Exchange *SEE ABOVE Misc. Charges _______ CA residents please add 8.25% sales tax Tax _______ ------------------------------------------------------ TOTAL $_______ Name: ________________________________________________________________ Company: _____________________________________________________________ Address: _____________________________________________________________ City: _________________________ State: _______ ZIP: _________-______ Data Phone #1: _______________________ Home Phone:___________________ Data Phone #2: _______________________ BBS Bps: _____________________ BBS Name: ____________________________________________________________ BBS Hours: _____________ Password For Quantum Leap!:_________________ If you are not already logged into Quantum Leap!, please give me a password to set up your account with. All checks must be drawn on US funds in US Dollars. Sorry, No COD orders will be accepted. -------------------------------------------------------------------------- C O P Y R I G H T N O T I C E S -------------------------------------------------------------------------- CircuitNET is Copyright (c) 1992 by Dave Stahl Spitfire is Copyright (c) 1987,1992 by Buffalo Creek Software. PKZIP and PKUNZIP are Copyright (c) 1990 by PKWare, Incorporated. Turbo Pascal is Copyright (c) 1989,1992 by Borland International. Turbo Pascal Reg. U.S. Pat. & Tm. Off. -------------------------------------------------------------------------- I would like to thank the following people who have helped in the making of this project. Bill Arlofski Steve Newman Wayne Letalien Bill Gray Glenn Lewis Lonnie Odom Michael Benedict Mike Ist Steve Palmer Lynn Hochwitz Sean Burbidge Mark Eastman Jere Issel What are you looking down here for? Get netmailing!