home *** CD-ROM | disk | FTP | other *** search
/ Beijing Paradise BBS Backup / PARADISE.ISO / software / BBSDOORW / GOLDED.RAR / GOLD / GOLD_JAM.DOC < prev    next >
Encoding:
Text File  |  1993-12-18  |  10.6 KB  |  266 lines
  1. ----------------------------------------------------------------------
  2. Information about the JAM implementation in GoldED.         Rev:931218
  3. ----------------------------------------------------------------------
  4.  
  5.  
  6. ----------------------------------------------------------------------
  7. --- Introduction
  8. ---
  9.  
  10. This document describes details about the implementation of the JAM
  11. messagebase format in GoldED. Should be read in conjunction with the
  12. JAM specs for better understanding.
  13.  
  14.  
  15. ----------------------------------------------------------------------
  16. --- General
  17. ---
  18.  
  19. The first release of the JAM messagebase specifications (JAM-001,
  20. rev.1, dated 93-07-01) included an example implementation in the C
  21. language of a "JAM API".
  22.  
  23. For the purpose of use in GoldED, the JAM API C implementation was
  24. both too complete and not complete enough. Therefore I developed my
  25. own specialized JAM msgbase handling code. My own code was of course
  26. designed be compatible with the original JAM API as well as the
  27. specifications, but some things are done slightly differently for
  28. various reasons.
  29.  
  30.  
  31. ----------------------------------------------------------------------
  32. --- File I/O checks
  33. ---
  34.  
  35. Reads and writes to the msgbase files are generally NOT checked for
  36. errors in GoldED. In contrast, the original JAM API checks everything
  37. and stores error values in the API, for the user to use or ignore.
  38.  
  39. Full checking degrades performance a bit, adds more code to the EXE
  40. file, and most importantly, GoldED just doesn't have a safe way to
  41. recover from the detection of such errors anyway at this time.
  42. Assuming that your system is working well, there are no harddisk
  43. errors etc., this will normally not be a problem.
  44.  
  45.  
  46. ----------------------------------------------------------------------
  47. --- Message header revisions
  48. ---
  49.  
  50. The JAM message headers contain a field to indicate the revision
  51. number of the header structure.
  52.  
  53. GoldED currently ignores this field and assumes that future revisions
  54. will remain backward compatible. When creating new msgs, GoldED uses
  55. the revision 1 header structure.
  56.  
  57. When new revisions of the JAM specs are released, GoldED will be
  58. updated to handle these as quickly as possible.
  59.  
  60.  
  61. ----------------------------------------------------------------------
  62. --- Passwords
  63. ---
  64.  
  65. The JAM specs contain fields for passwords to access the msgbase
  66. and/or indiviual messages.
  67.  
  68. GoldED currently doesn't support these passwords. When creating a new
  69. JAM msgbase and/or new JAM msgs, GoldED sets the password to
  70. FFFFFFFFh. If you change an existing msg which has a password, the
  71. password is NOT preserved, but reset to FFFFFFFFh.
  72.  
  73.  
  74. ----------------------------------------------------------------------
  75. --- Lastreads
  76. ---
  77.  
  78. The JAM lastread file is designed such that is has to be searched for
  79. a userid/usercrc, because one cannot assume that the records are in a
  80. specific order.
  81.  
  82. The JAM API searches the userid field. However it seems more
  83. reasonable to search for the usercrc, because that is a value the
  84. program can calculate from the username without looking in other
  85. files. I'm not sure why the JAM API chooses to look in the userid
  86. field instead. GoldED searches for the usercrc, not the userid. In any
  87. case, it seems that RemoteAccess 2.x sets both the userid and usercrc
  88. to the same value.
  89.  
  90. The specs state that the user's lastread record must be searched for
  91. both when retrieving it and storing an updated record. However, the
  92. JAM API seems to implemented slightly differently, because when it
  93. stores an updated record, it stores it at the same position as it was
  94. read *without* first searching for it.
  95.  
  96. GoldED has been implemented to work in a similar manner. It searches
  97. for the user's lastread record when the msgbase is opened, and it
  98. assumes that it will remain in the same position as it was found,
  99. until the msgbase is closed.
  100.  
  101. This is normally a quite reasonable assumption. The only circumstance
  102. where the lastread records might be re-ordered is when a msgbase
  103. maintentance utility cleans up or sorts, and such a utility is
  104. normally designed to open the msgbase files in exclusive mode, which
  105. it can't do when the files are already open. If it tries to re-order
  106. without exclusive access, the utility is badly designed and
  107. potentially dangerous in multitask/networking environments.
  108.  
  109.  
  110. ----------------------------------------------------------------------
  111. --- Size limits
  112. ---
  113.  
  114. The JAM specs allow msgbases and msgs of really huge sizes. The 16-bit
  115. DOS version of GoldED cannot handle the full extremes of this. The
  116. 32-bit OS/2 and 32-bit protected mode DOS versions of GoldED can
  117. handle any size, only restricted by memory, disk space or unknown
  118. compiler or operating system limits.
  119.  
  120. The internal limits for the 16-bit versions of GoldED means that they
  121. can only handle msgbases containing a maximum of 8191 msgs (including
  122. deleted msgs), and msgs a maximum of about 64k long. In theory at
  123. least. In practice the limits may be smaller due to lack of memory.
  124.  
  125.  
  126. ----------------------------------------------------------------------
  127. --- ASCII 7-bit escaping
  128. ---
  129.  
  130. GoldED currently doesn't support the escaping described in the JAM
  131. specs. The specs state that the current revision of JAM does not
  132. support it either, so I guess it's no great loss.
  133.  
  134.  
  135. ----------------------------------------------------------------------
  136. --- Date fields
  137. ---
  138.  
  139. GoldED currently doesn't display the DateReceived field, but it is
  140. updated on disk when a message is received (read) by the recipient.
  141.  
  142. The DateProcessed field is set to the current date when a msg is
  143. writtten or changed with GoldED.
  144.  
  145. All new dates are set to the system time and are not adjusted for
  146. timezone.
  147.  
  148.  
  149. ----------------------------------------------------------------------
  150. --- Subfields
  151. ---
  152.  
  153. The concept of the JAM subfields is difficult to support easily in a
  154. program like GoldED, which was designed to support the traditional
  155. fixed header formats and kludges in the msg body. Therefore the
  156. implementation in GoldED of the JAM subfields is not currently as
  157. complete as one might wish.
  158.  
  159. However, it should be adequate for most purposes. I will of course do
  160. what I can to improve the JAM subfield support in future releases. The
  161. following is a list of the current limitations of the JAM subfield
  162. support in GoldED:
  163.  
  164. *   Subfields are converted internally to the equivalent kludges for
  165.     easy viewing, and to make it possible to copy JAM msgs to areas
  166.     with other msgbase formats. Some subfields do not have equivalent
  167.     known kludges defined. They are converted to kludges with names I
  168.     have invented for the purpose. All subfields can be viewed if you
  169.     hit the Alt-I key to display a hexdump of the message.
  170.  
  171. *   The subfields with size limits (typically 100 chars) are not
  172.     specifically checked for size. Since all other msgbase systems
  173.     have much lower limits for the fields in question, this should not
  174.     be a problem.
  175.  
  176. *   Only one OADDRESS/DADDRESS is supported. When reading a message,
  177.     only the _first_ OADDRESS/DADDRESS is used.
  178.  
  179. *   None of the file attach or file request subfields are supported at
  180.     this time. File attaches or file requests are stored in the
  181.     subject field in a manner similar to other msgbase formats. This
  182.     might not be supported by a fully JAM compliant mail processor,
  183.     but IMHO a mail processor should use the subject field if it finds
  184.     the file attach/request attributes set, but can't find any
  185.     subfields for them.
  186.  
  187. *   If you change a JAM message which is not from you, and save it,
  188.     all unsupported subfields will be missing in the saved message,
  189.     and some supported subfields may be changed in content (like the
  190.     PID subfield).
  191.  
  192. *   Currently unsupported message attributes:
  193.  
  194.     MSG_FPU     "Force pickup"
  195.     MSG_NODISP  "Msg may not be displayed to user" (always displayed)
  196.  
  197.  
  198. ----------------------------------------------------------------------
  199. --- Deleted msgs
  200. ---
  201.  
  202. The original JAM specs has a fairly major problem when it comes to the
  203. specification for deleting msgs and in particular about _detecting_
  204. deleted msgs. The original specs do not define a fast way to detect
  205. deleted msgs from the index file alone.
  206.  
  207. This may not be so important for a BBS or a mail processor, but it is
  208. absolutely vital for mail readers such as GoldED, which need a fast
  209. way to find out how many active msgs there are, and where the lastread
  210. is, and to calculate how many unread msgs there are. If GoldED had
  211. scan the header file to check a single bit in each header the area
  212. scanning would slow down dramatically, because the header file can
  213. easily grow to many megabytes and thousands of msgs.
  214.  
  215. Fortunately there is a way out. The specs state that if the usercrc
  216. and header offset values in the index are both -1 (FFFFFFFFh), then
  217. "there is no corresponding header". Such a situation is IMHO highly
  218. unlikely, so I have proposed to use this to signify a deleted msg
  219. instead. This should be backward compatible with almost all JAM
  220. compatible programs, with the possible exception of msg undelete
  221. utilities.
  222.  
  223. With the header offset set to -1 (FFFFFFFFh), there is of course no
  224. fast way to find the header of a deleted msg. A msg undelete utility
  225. would have to scan through the entire header file to locate the
  226. deleted header (or rather the last occurrence of it, because there can
  227. easily exist more than one deleted header with the same message
  228. number). This is IMHO a price worth paying for the performance gained
  229. by using by changing the specs to specify a deleted msg instead of a
  230. hypothetical non-existing header.
  231.  
  232. When I brought up this subject in the JAMDEV echo, the developers who
  233. replied generally agreed that this was a good idea. At the time of
  234. writing, I don't know for certain that it will be changed in the
  235. specs, but I think so.
  236.  
  237. GoldED follows my proposed method when deleting msgs. An index entry
  238. with a header offset of -1 (FFFFFFFFh) counts as a deleted msg.
  239.  
  240.  
  241. ----------------------------------------------------------------------
  242. --- Reply links
  243. ---
  244.  
  245. GoldED currently does not support or maintain the "Reply1st" field.
  246.  
  247. The method of linking msgs when replying with GoldED is definable with
  248. the REPLYLINK keyword in GOLDED.CFG. The REPLYLINK keyword is currenly
  249. only documented in the NOTE*.DOC file.
  250.  
  251.  
  252. ----------------------------------------------------------------------
  253. --- Credits
  254. ---
  255.  
  256. JAM(mbp) - Copyright 1993 Joaquim Homrighausen, Andrew Milner,
  257.                           Mats Birch, Mats Wallin.
  258.                           ALL RIGHTS RESERVED.
  259.  
  260. Enjoy!
  261.  
  262. Odinn Sorensen
  263. December 18, 1993
  264.  
  265. ----------------------------------------------------------------------
  266.