home *** CD-ROM | disk | FTP | other *** search
/ Crawly Crypt Collection 1 / crawlyvol1.bin / bbs / mdiff103 / maxidiff.doc < prev    next >
Text File  |  1993-08-31  |  17KB  |  415 lines
  1. ***  **   Maxi*DIFF 1.03<beta> by Erik Williams
  2. **  ***   SunFox Productions, Ltd. <Raleigh, NC>
  3. ***  **   (c) Copyright, 1993.  All rights reserved.
  4. **  ***   "Jesus saves, Gretzky gets the rebound...SCORES!"
  5.  
  6.                      PRELIMINARY DOCUMENTATION
  7.  
  8. LAST MODIFIED:  August 31st, 1993
  9.  
  10. FILES IN ARCHIVE:
  11.  
  12.    MAXIDIFF.TOS => the executable
  13.    MAXIDIFF.CFG => config file...must be in Maxi*DIFF's directory!
  14.    MAXIDIFF.DOC => this documentation
  15.  
  16. Bill, for right now, let's keep Maxi*DIFF between us until I'm reasonably
  17. sure the bugs are out of the programme.  After I'm convinced that the most
  18. hairy bugs are gone, then we can go for a hatch via AFDS (with the BBS
  19. utilities I'm writing, I may ask for a file echo of my own...ASUNFOX...I
  20. like the sound of that!  ;)
  21.  
  22. INTRODUCTION:
  23.  
  24. Everyone who is in a Fidonet-style network knows the importance of the
  25. nodelist...the whole network comes to its knees without this vital piece
  26. of routing information.  Most sysops probably think that the nodelist
  27. comes into being by magical incantations, but it's really the result of
  28. the hard work of the administrative nodes to keep everyone's nodelist
  29. entry in order.
  30.  
  31. Hopefully, Maxi*DIFF will make this task a bit easier.  While Maxi*DIFF
  32. is still beta code, all of the essential functions are fully operational.
  33. Things that are on the list of things to do include nodediff generation
  34. as well as a much improved user interface...
  35.  
  36. This programme is really only meant for hosts and higher...the average
  37. sysop won't have a need for Maxi*DIFF.  In fact, anyone currently using
  38. MakeDiff/ST (by Dave Thomas of Automagic) may use Maxi*DIFF as a direct
  39. replacement.
  40.  
  41. This isn't a knock on MakeDiff/ST...it's a very fine programme in its
  42. own right and I hope that Maxi*DIFF eventually comes close to MakeDiff
  43. in terms of power and features (after all, MakeDiff is the standard I'm
  44. using as a basis for my own work).
  45.  
  46. CONFIGURING THIS BUGGER:
  47.  
  48. Configuring Maxi*DIFF to do as you wish is relatively simple...MAXIDIFF.CFG
  49. is pretty much free-format in terms of spacing...feel free to indent as you
  50. wish...Maxi*DIFF's parser isn't fazed by block-style lines.  In fact, I
  51. highly encourage a block-format...it makes reading and fixing the config
  52. file that much easier!  A sample of this is the MAXIDIFF.CFG I have 
  53. included in this archive.
  54.  
  55. REQUIRED CONFIGURATION LINES:
  56.  
  57. There are only three keywords that must be in the config file for Maxi*DIFF
  58. to work properly...LogFile, LogLevel, and NetMail.
  59.  
  60. LogFile <path and filename of log>
  61.  
  62.           ex.  LogFile g:\logs\maxidiff.log
  63.  
  64.     LogFile is simply the path and filename that you wish the logging to
  65. be written to.  I use the standard Binkley logging format, so you can use
  66. your main log or one of your choosing...either way is fine.
  67.  
  68.  
  69. LogLevel <1|2>
  70.  
  71.           ex.  LogLevel 2
  72.  
  73.     LogLevel specifies the verbosity of the logging...right now, there
  74. isn't a whole lot of difference between levels 1 and 2, so I suggest
  75. LogLevel 2 for a while...there will be more levels possible as more
  76. features are added.
  77.  
  78. NetMail <path and file "stub" of your netmail HDR/MSG files>
  79.  
  80.           ex.  g:\netmail\netmail
  81.  
  82.     This tells me where the message and header files for your netmail
  83. base are...Maxi*DIFF will generate netmail notification when a segment
  84. is produced.  Generally, if you distribute the nodelist, Maxi*DIFF will
  85. notify you of the CRC, SIZE, and NAME of the nodelist in netmail.  If you
  86. are a zone or lower, then it will generate the netmail for you and one
  87. for the sysop of the system to whom you submit your nodelist segment
  88. and will submit your segment via netmail file-attach.
  89.  
  90.  
  91. CONFIGURING YOUR ADMINISTRATIVE ZONES
  92.  
  93.  
  94. For each zone in which you are a host or higher, all of the information
  95. to generate a nodelist/nodediff/segment will be contained in a block
  96. configuration of the form Zone...EndZone.
  97.  
  98. There are two different ways of configuring these Zones depending on
  99. what type of coordinator you are.  If you are the generator of the nodelist
  100. for an entire network, then your configuration will be of the "Distribution"
  101. type.  Anything else is of the "submittal" type (as you will generally
  102. submit your segment to a higher coordinator).
  103.  
  104. I'll discuss each type and how it is utilised first, then give the
  105. keywords that may be found within a Zone...EndZone block.  In general, you
  106. may have as many of these Zones as you wish (or more accurately, as memory
  107. permits!)...know that for each zone, 7K will be used for the configuration
  108. of the zone plus 128 bytes x the number of nodelist segment files in your
  109. segment.  This shouldn't break anyone with less than 25 networks to
  110. administrate!  ;)  The list of administrative zones is now kept in a
  111. linked-list (with a linked-list within a Zone block for the segments) which
  112. will only consume as much memory as it needs rather than waste a lot of
  113. memory on an array based structure.  I will lose a bit of speed because
  114. of the way a linked list must be traversed, but I will save a lot of
  115. precious memory this way.
  116.  
  117. Only one other restriction is that the keywords must be capitalised
  118. exactly or Maxi*DIFF won't recognise it.
  119.  
  120.  
  121. THE DISTRIBUTION CONFIGURATION
  122.  
  123. The distribution configuration will be used by coordinators who run their
  124. own networks...i.e. the International Coordinator of FidoNet, the Zone
  125. Coordinator of AtariNet, and so forth.  These are the people who generate
  126. the full nodelist and distribute it down through the network below them.
  127.  
  128. A distribution configuration will be of the form:
  129.  
  130. Zone 17
  131.     Domain         PerotNet
  132.     Coordinator    Erik Williams
  133.     CoordAddress   17:1/0
  134.     CoordType      Distribution
  135.     ProcessDay     Friday
  136.     ProcessTimes   00:00:00 23:59:59
  137.     Header         g:\turbo\bink\makediff\nl_text\head.txt
  138.     Copyright      g:\turbo\bink\makediff\nl_text\c_write.txt
  139.     Trailer        g:\turbo\bink\makediff\nl_text\tail.txt
  140.     Nodelist
  141.        Segment        g:\turbo\bink\makediff\segments\zone17.seg
  142.        Segment        g:\turbo\bink\makediff\segments\reg200.seg
  143.        Segment        g:\turbo\bink\makediff\segments\reg300.seg
  144.     EndNodelist
  145.     Archiver       f:\turbo\bink\whatarc\arc602.ttp
  146.     ArcLetter      A
  147.     ArcParams      a %s %s%s
  148.     ListName       PEROLIST
  149.     DiffName       PERODIFF
  150.     OutputPath     g:\turbo\bink\makediff\master\
  151. EndZone
  152.  
  153. It's highly recommended that you use all of these keywords to get the
  154. full functionality out of Maxi*DIFF.  You may omit the Header, Copyright,
  155. and Trailer lines if you wish...leaving anything else out is likely to have
  156. unexpected behaviour on the part of Maxi*DIFF!  Make sure you have an
  157. EndZone at the end of each zone...it's my way of telling that it is time
  158. to start working on a configuring a new zone!
  159.  
  160.  
  161. THE SUBMITTAL CONFIGURATION
  162.  
  163. A submittal configuration will be used by all other types of coordinators.
  164. Action is the same no matter what type of coordinator you are, but here
  165. are the coordinator types that are possible and the way they would be used
  166. in a submittal configuration.
  167.  
  168.     Host/Region => This is the most common...a host that sends a nodelist
  169.                    segment up the network to the RC or ZC, respectively.
  170.  
  171.     Zone => This is only useful for zone coordinators who are in a network
  172.             that is multi-zone and still submit a nodelist to a higher
  173.             power.  FidoNet is a perfect example of this...the Z1C still
  174.             submits the Z1 nodelist segment to the IC.
  175.  
  176. The most important change from MakeDiff/ST is the handling of multiple
  177. "hats".  Suppose you are a Region and a Host in AtariNet.  Under MakeDiff,
  178. you'd have to run MakeDiff for your host segment, then again for your
  179. regional segment.  In Maxi*DIFF, pick the HIGHEST coordinator position
  180. for your submittal configuration!
  181.  
  182. The reason for this is that Maxi*DIFF allows you to specify the order
  183. in which your segment files are merged into a submittal nodelist segment
  184. so all you have to do is just define your host segment where you want it
  185. to be in the nodelist segment you are creating...and then just run
  186. Maxi*DIFF once for your regional configuration!
  187.  
  188.  
  189. A submittal configuration looks like this:
  190.  
  191. Zone 51
  192.     Domain         AtariNet
  193.     Coordinator    Erik Williams
  194.     CoordAddress   51:102/0
  195.     CoordType      Host
  196.     Submit         51:1/0
  197.     ProcessDay     Friday
  198.     ProcessTimes   00:00:00 23:59:59
  199.     Nodelist
  200.        Segment        g:\turbo\bink\makediff\segments\host102.seg
  201.     EndNodelist
  202.     ListName       ATAR102
  203.     OutputPath     g:\turbo\bink\makediff\master\
  204. EndZone
  205.  
  206. As you can see, the only real differences between the two types are that
  207. the Header, Copyright, and Trailer lines are not present.  You may define
  208. them, but Maxi*DIFF will ignore them.  Also, a submittal configuration at
  209. the host level is likely to have only one segment file.
  210.  
  211.  
  212. THE ZONE CONFIGURATION KEYWORDS
  213.  
  214. These need not be in any particular order, though the nodelist segments
  215. should be kept together in a Nodelist...EndNodelist block.
  216.  
  217.  
  218. Domain <eight character domain name>
  219.  
  220.           ex.  Domain PerotNet
  221.  
  222.     The Domain keyword specifies your domain name...please limit it to
  223. eight characters.  You may capitalise as you please...when Maxi*DIFF
  224. generates the netmail kludge lines, it'll change it to all lowercase as
  225. needed.
  226.  
  227.  
  228. Coordinator <your name>
  229.  
  230.           ex.  Coordinator Erik Williams
  231.                Coordinator Erik Williams, NC102
  232.  
  233.     The Coordinator keyword allows you to personalise your netmails.  The
  234. only limit is 30 characters of any type.
  235.  
  236.  
  237. CoordAddress <your administrative address>
  238.  
  239.           ex.  CoordAddress 51:102/0
  240.  
  241.     CoordAddress is the address of your administrative node (which will
  242. always be of the form zone:net/0.  You need not specify the domain (as it
  243. is already done) nor the point (it is assumed to be zero...I've never known
  244. of a point that was a coordinator).
  245.  
  246.  
  247. CoordType <Hub|Host|Region|Zone|Distribution>
  248.  
  249.           ex.  CoordType Distribution
  250.  
  251.     The CoordType specifies the type of coordinator you are...anything
  252. other than Distribution is assumed to be a submittal configuration.
  253. Remember to pick your highest coordinator level when using a submittal
  254. configuration!
  255.  
  256.     (Hubs are supported, but I haven't known of a hub that submits their
  257. own nodelist segment...but anything's possible!).
  258.  
  259.  
  260. ProcessDay <Sunday|Monday|Tuesday|Wednesday|Thursday|Friday|Saturday>
  261.  
  262.           ex.  ProcessDay Thursday
  263.  
  264.     This should be obvious...maintain the capitalisation of the day as
  265. I'm comparing it to a system-standard result string.  :)
  266.  
  267. ProcessTimes <start> <end>
  268.  
  269.           ex.  ProcessTimes 17:00:00 17:05:00
  270.  
  271.     This allows you to specify the time that a nodelist will be generated
  272. accurate to within one second of executing Maxi*DIFF!  This gives you a
  273. great amount of flexibility.  Be sure to use the hh:mm:ss format and use
  274. *MILITARY* times (it makes the comparisons that much easier!).
  275.  
  276.  
  277. Header <path and filename>
  278.  
  279.           ex.  Header g:\turbo\bink\makediff\nl_text\head.txt
  280.  
  281.     The header file will be the first file included in the distribution
  282. nodelist.  Generally, this is used for announcements and topology reports.
  283. All lines in this file should be comments and use the standard FidoNet
  284. commenting conventions, i.e. ;A  or ;S , as the first three characters
  285. of the line!
  286.  
  287.  
  288. Copyright <path and filename>
  289.  
  290.           ex.  Copyright g:\turbo\bink\makediff\nl_text\c_write.txt
  291.  
  292.     The copyrights will be the second file included in the distribution
  293. nodelist.  Generally, this is used for copyright announcements.  All lines
  294. in this file should be comments and use the standard FidoNet commenting
  295. conventions, i.e. ;A  or ;S , as the first three characters of the line!
  296.  
  297.  
  298. Trailer <path and filename>
  299.  
  300.           ex.  Copyright g:\turbo\bink\makediff\nl_text\c_write.txt
  301.  
  302.     The copyrights will be the last file included in the distribution
  303. nodelist.  Generally, this is used for welcomes to the network, etc.  All
  304. lines in this file should be comments and use the standard FidoNet
  305. commenting conventions!
  306.  
  307.  
  308. Nodelist...EndNodelist
  309.  
  310.     This is the most important part of the nodelist configuration...this
  311. is where you will list your segments in the order you wish them to appear
  312. in your nodelist!
  313.  
  314.           ex.  Nodelist
  315.                  Segment        g:\turbo\bink\makediff\segments\zone17.seg
  316.                  Segment        g:\turbo\bink\makediff\segments\reg200.seg
  317.                  Segment        g:\turbo\bink\makediff\segments\reg300.seg
  318.                EndNodelist
  319.                     
  320.     Within each Nodelist/EndNodelist pair, there will be one or more
  321. Segment directives.  Remember to make sure they are in the exact order
  322. you wish them to appear in the nodelist!!!
  323.  
  324.  
  325. Archiver <path and filename>
  326.  
  327.           ex.  Archiver f:\turbo\bink\whatarc\arc602.ttp
  328.  
  329.     This is the complete path and filename for your archiving programme.
  330. Archiver is only used in Distribution configurations...if it is present
  331. in a submittal configuration, it will be ignored.  Also, the Archiver is
  332. an optional keyword...if you don't specify it, your nodelist will be
  333. left in it's raw state!
  334.  
  335.  
  336. ArcLetter <single CAPITAL character>
  337.  
  338.           ex.  ArcLetter A
  339.  
  340.     The ArcLetter is the letter that will be placed in the first position
  341. of the filename extension of your compressed nodelist.  For example, say
  342. Maxi*DIFF generates a nodelist named ATARLIST.239.  When it gets
  343. compressed (in this example, by ARC602), the resulting filename of the
  344. compressed version will be ATARLIST.A39.
  345.  
  346.  
  347. ArcParams <parameters and wildcards>
  348.  
  349.           ex.  ArcParams a %s %s%s
  350.  
  351.     This is the trickiest bit of configuration in MAXIDIFF.CFG.  In
  352. general, the first parameter will be whatever command your archiver uses
  353. to add to existing/create archives...in this example ARC602 simply uses
  354. the a command.  Following the command may be a list of optional modifiers
  355. which may affect the compression.
  356.  
  357.     Somewhere in the ArcParams string must be three %s substrings.  The
  358. first %s will be replaced with the path/filename of the resulting archive,
  359. the second %s will be replaced with the output path (as specified in
  360. OutputPath), and the third %s will be replaced with the filename of the
  361. uncompressed nodelist.
  362.  
  363.     The reason for this method is because of some archivers that want a
  364. space between the second and third %s...in particular, the Quester LZH.
  365. For Quester's LZH, I'd use an ArcParams string like "a %s %s %s".
  366.  
  367.     Best suggestion is for you to play with it until it works the
  368. way you wish.  If you have more or less than three %s directives, then
  369. I can guarantee a bus error will be in your future!  :)
  370.  
  371.  
  372. ListName <first eight characters of nodelist filename>
  373.  
  374.           ex.  ListName PEROLIST
  375.  
  376.      This will be the name of your nodelist (or submittal segment) minus
  377. the extension (which is generated by Maxi*DIFF).  For a Distribution
  378. configuration, the extension will be the Julian day that the nodelist is
  379. created...for submissions, the extension will be SEG.  It shouldn't matter
  380. if the Listname is in all caps or not.
  381.  
  382.  
  383. DiffName <first eight characters of nodediff filename>
  384.  
  385.           ex.  Listname PERODIFF
  386.  
  387.      This will be the name of your nodelist difference file...the extension
  388. will be the Julian day that it is created.  This has no effect at the
  389. moment, but nodediff creation will be supported in a future version.
  390.  
  391.  
  392. OutputPath <path with trailing backslash
  393.  
  394.           ex.  OutputPath g:\turbo\bink\makediff\master\
  395.  
  396.      The output path is where the final nodelist (or segment) will be
  397. created...and when file archiving is available from Maxi*DIFF, the arced
  398. version of the nodelist will also be here.  I use this directory to
  399. generate a RAW nodelist file (essentially, a nodelist without a header
  400. line) so I can calculate the CRC of the file (the RAW file is deleted when
  401. the final nodelist is completely generated).
  402.  
  403.  
  404. FINAL COMMENTS:
  405.  
  406. That should about do it...admittedly, the code is still a bit rough, but
  407. in weeks of testing, it's done the job here.  It works on the TT030 and
  408. should work on a Mega4STE.
  409.  
  410. Any comments/bug reports you may have, please let me know so I can fix them.
  411. I'm usually in Fayetteville (NC) on the weekends, but I'll be back on Sunday
  412. night round 2300 hours or so.
  413.  
  414. SunFox
  415.