Click above to get retro games delivered to your door ever month!

                           JAM Implementation Notes


     This chapter describes details about the implementation of the  JAM
     messagebase format in  GoldED. Should be  read in conjunction  with
     the JAM specs  for better understanding.  A lot of  technical terms
     will be used, so if you are not the technical type, just skip  over
     it.


     General notes

     The first release of  the JAM messagebase specifications  (JAM-001,
     rev.1, dated 93-07-01) included an example implementation in the  C
     language of a "JAM API".

     For the purpose of use in GoldED, the JAM API C implementation  was
     both too complete and not complete enough. Therefore I developed my
     own  specialized  JAM  msgbase  handling  code.  My own code was of
     course designed be compatible with the original JAM API as well  as
     the specifications, but some  things are done slightly  differently
     for various reasons.


     File I/O checks

     Reads and writes to the msgbase files are generally NOT checked for
     errors  in  GoldED.  In  contrast,  the  original  JAM  API  checks
     everything and stores error values in the API, for the user to  use
     or ignore.

     Full checking degrades performance a bit, adds more code to the EXE
     file, and most importantly, GoldED just doesn't have a safe way  to
     recover from  the detection  of such  errors anyway  at this  time.
     Assuming that your  system is working  well, there are  no harddisk
     errors etc., this will normally not be a problem.


     Message header revisions

     The JAM message  headers contain a  field to indicate  the revision
     number of the header structure.

     GoldED  currently  ignores  this  field  and  assumes  that  future
     revisions will remain backward compatible. When creating new  msgs,
     GoldED uses the revision 1 header structure.

     When new revisions  of the JAM  specs are released,  GoldED will be
     updated to handle these as quickly as possible.


     Passwords

     The JAM specs  contain fields for  passwords to access  the msgbase
     and/or indiviual messages.

     GoldED currently doesn't support  these passwords. When creating  a
     new JAM msgbase  and/or new JAM  msgs, GoldED sets  the password to
     FFFFFFFFh. If you change an existing msg which has a password,  the
     password is NOT preserved, but reset to FFFFFFFFh.


     Lastreads

     The JAM lastread file is designed  such that is has to be  searched
     for a userid/usercrc,  because one cannot  assume that the  records
     are in a specific order.

     The  JAM  API  searches  the  userid  field.  However it seems more
     reasonable to search for the  usercrc, because that is a  value the
     program can calculate  from the username  without looking in  other
     files. I'm not sure why the  JAM API chooses to look in  the userid
     field instead. GoldED searches for the usercrc, not the userid.  In
     any case, it seems that  RemoteAccess 2.x sets both the  userid and
     usercrc to the same value.

     The specs state  that the user's  lastread record must  be searched
     for both when retrieving it and storing an updated record. However,
     the JAM API seems to implemented slightly differently, because when
     it stores an updated record, it  stores it at the same position  as
     it was read *without* first searching for it.

     GoldED  has  been  implemented  to  work  in  a  similar manner. It
     searches for the user's lastread record when the msgbase is opened,
     and it assumes that it will  remain in the same position as  it was
     found, until the msgbase is closed.

     This  is  normally   a  quite  reasonable   assumption.  The   only
     circumstance where the lastread records might be re-ordered is when
     a  msgbase  maintentance  utility  cleans  up  or sorts, and such a
     utility is normally designed to open the msgbase files in exclusive
     mode, which  it can't  do when  the files  are already  open. If it
     tries to re-order  without exclusive access,  the utility is  badly
     designed   and   potentially   dangerous   in  multitask/networking
     environments.


     Size limits

     The JAM  specs allow  msgbases and  msgs of  really huge sizes. The
     16-bit DOS  version of  GoldED cannot  handle the  full extremes of
     this. The  32-bit OS/2  and 32-bit  protected mode  DOS versions of
     GoldED can handle any size,  only restricted by memory, disk  space
     or unknown compiler or operating system limits.

     The internal limits  for the 16-bit  versions of GoldED  means that
     they can  only handle  msgbases containing  a maximum  of 8191 msgs
     (including deleted msgs), and msgs a maximum of about 64k long.  In
     theory at least. In practice the limits may be smaller due to  lack
     of memory.


     ASCII 7-bit escaping

     GoldED currently doesn't support the escaping described in the  JAM
     specs. The specs  state that the  current revision of  JAM does not
     support it either, so I guess it's no great loss.


     Date fields

     GoldED currently doesn't display the DateReceived field, but it  is
     updated on disk when a message is received (read) by the recipient.

     The DateProcessed field is  set to the current  date when a msg  is
     writtten or changed with GoldED.

     All new dates are set to  the system time and are not  adjusted for
     timezone.


     Subfields

     The concept of the JAM subfields is difficult to support easily  in
     a  program  like  GoldED,  which   was  designed  to  support   the
     traditional  fixed  header  formats  and  kludges  in the msg body.
     Therefore the implementation in GoldED of the JAM subfields is  not
     currently as complete as one might wish.

     However, it should be adequate for most purposes. I will of  course
     do  what  I  can  to  improve  the  JAM  subfield support in future
     releases. The following is a list of the current limitations of the
     JAM subfield support in GoldED:

     *  Subfields are converted internally to the equivalent kludges for
        easy viewing, and to make it possible to copy JAM msgs to  areas
        with  other  msgbase  formats.   Some  subfields  do  not   have
        equivalent known kludges defined. They are converted to  kludges
        with names I have invented for the purpose. All subfields can be
        viewed if  you hit  the Alt-I  key to  display a  hexdump of the
        message.

     *  The subfields with size limits (typically 100 chars) are not
        specifically checked for size. Since all other msgbase systems
        have much lower limits for  the fields in question, this  should
        not be a problem.

     *  Only one OADDRESS/DADDRESS is supported. When reading a message,
        only the _first_ OADDRESS/DADDRESS is used.

     *  None of the file attach or file request subfields are supported
        at this time. File attaches  or file requests are stored  in the
        subject field in a manner similar to other msgbase formats. This
        might not be supported by a fully JAM compliant mail  processor,
        but IMHO  a mail  processor should  use the  subject field if it
        finds the file attach/request attributes set, but can't find any
        subfields for them.

     *  If you change a JAM message which is not from you, and save it,
        all unsupported subfields will be missing in the saved message,
        and some supported subfields may be changed in content (like the
        PID subfield).

     *   Currently unsupported message attributes:

        MSG_FPU    "Force pickup"
        MSG_NODISP "Msg may not be displayed to user" (always displayed)


     Deleted msgs

     The original JAM specs has a fairly major problem when it comes  to
     the  specification  for  deleting  msgs  and  in  particular  about
     _detecting_ deleted msgs. The original  specs do not define a  fast
     way to detect deleted msgs from the index file alone.

     This may not be so important for a BBS or a mail processor, but  it
     is absolutely vital for mail  readers such as GoldED, which  need a
     fast way to find out how many active msgs there are, and where  the
     lastread is, and  to calculate how  many unread msgs  there are. If
     GoldED had  scan the  header file  to check  a single  bit in  each
     header the area scanning would slow down dramatically, because  the
     header file  can easily  grow to  many megabytes  and thousands  of
     msgs.

     Fortunately there is a way out. The specs state that if the usercrc
     and header offset values in the index are both -1 (FFFFFFFFh), then
     "there is no corresponding header". Such a situation is IMHO highly
     unlikely, so I have proposed to  use this to signify a deleted  msg
     instead. This  should be  backward compatible  with almost  all JAM
     compatible programs,  with the  possible exception  of msg undelete
     utilities.

     With the header offset set to -1 (FFFFFFFFh), there is of course no
     fast  way  to  find  the  header  of  a deleted msg. A msg undelete
     utility would have to scan through the entire header file to locate
     the deleted header  (or rather the  last occurrence of  it, because
     there can easily exist more  than one deleted header with  the same
     message  number).  This  is  IMHO  a  price  worth  paying  for the
     performance gained  by using  by changing  the specs  to specify  a
     deleted msg instead of a hypothetical non-existing header.

     When I brought up this  subject in the JAMDEV echo,  the developers
     who replied generally agreed that this was a good idea. At the time
     of writing, I don't know for certain that it will be changed in the
     specs, but I think so.

     GoldED optionally  (since version  2.50.B0822) follows  my proposed
     method when deleting msgs. The configuration keyword  JAMHARDDELETE
     specifies which method to  use. If set to  Yes, my method is  used.
     The default is No, but I recommend (and use myself) Yes.


     Scanning files

     The  NETMAIL/ECHOMAIL.JAM  files   are  written/updated  when   new
     messages are written or changed in JAM netmail/echomail areas.  The
     files  are  written/updated  in  the  JAMPATH.  If you don't have a
     JAMPATH, it defaults to the  HUDSONPATH. If you don't use  a Hudson
     msgbase and haven't defined  a HUDSONPATH, the HUDSONPATH  defaults
     to the GOLDPATH.

     At the time  of writing, the  NETMAIL/ECHOMAIL.JAM files are  not a
     part of the official JAM specs,  but they are used in RA2  and most
     JAM compatible mail processors to specify the msgs that need to  be
     exported from the JAM msgbase files.